etx

Documentation

Overview

Package etx uses logging to make extended transactions from a sequence of operations.

For example it allows a web server request to be split between an immediate operation and asynchronous completion, with a guarantee that the second part will be completed even if the server is restarted between the two parts. It also allows responsibility for continuing the extended transaction to be passed between resource managers.

Index

• func String(id TxId) string
• func Timestamp(id TxId) time.Time
• type App
• type Op
• type RM
• type Redo
• type RedoStore
• type TM
  • func New(app App, store RedoStore) *TM
  • func (tm *TM) Begin() TxId
  • func (tm *TM) BeginNext(first TxId, rm RM, opType int, op Op) error
  • func (tm *TM) DoNext(id TxId)
  • func (tm *TM) End(id TxId) error
  • func (tm *TM) Recover(mgrs ...RM) error
  • func (tm *TM) SetNext(id TxId, rm RM, opType int, op Op) error
  • func (tm *TM) Timeout(rm RM, opType int, before time.Time) error
• type TxId
  • func Id(s string) (TxId, error)

Functions

func String

func String(id TxId) string

String formats a transaction ID.

func Timestamp

func Timestamp(id TxId) time.Time

Timestamp returns the start time of an extended transaction.

Types

type App

type App interface {
	// Log optionally records an error
	Log(error) // ## not used
}

App is the interface to functions provided by the parent application.

type Op

type Op interface {
}

Op is the interface to an RM operation. Operations must either be database transactions or idempotent.

type RM

type RM interface {
	Name() string                         // manager name, for the redo log
	ForOperation(opType int) Op           // return operation struct to receive unmarshalled data
	Operation(id TxId, opType int, op Op) // operation for execution
}

RM is the interface for a resource manager, which implements operations. ## The id parameter is clumsy, because the RM will need to embed it in the op before calling a worker, ## so that the worker can choose to end the transaction :-(.

type Redo

type Redo struct {
	Id        int64  // transaction ID
	Manager   string // resource manager name
	OpType    int    // operation type
	Operation []byte // operation arguments, in JSON
}

Transaction struct holds the stored data for a transaction.

type RedoStore

type RedoStore interface {
	All() []*Redo                               // all redo log entries in ID order
	DeleteId(id int64) error                    // delete redo
	ForManager(rm string, before int64) []*Redo // aged log entries for RM
	GetIf(id int64) (*Redo, error)              // get entry if it still exists
	Insert(t *Redo) error                       // add entry
	Update(t *Redo) error                       // update entry
}

RedoStore is the interface for storage of extended transactions, implemented by the parent application. The store must implement database transactions so that tx.Redo records are stored either: (1) with the associated RM database transaction, or (2) before the associated RM idempotent operation.

type TM

type TM struct {
	// contains filtered or unexported fields
}

TM holds transaction manager state, and dependencies of this package on the parent application. It has no state of its own.

func New

func New(app App, store RedoStore) *TM

New initialises the transaction manager and recovers all logged operations. ## Separate func to add RMs?

func (*TM) Begin

func (tm *TM) Begin() TxId

Begin returns the transaction ID for a new extended transaction.

func (*TM) BeginNext

func (tm *TM) BeginNext(first TxId, rm RM, opType int, op Op) error

BeginNext starts another extended transaction, with an operation executed after the first one. It's just a convenience to avoid multiple DoNext calls when a set of extended transactions are started at the same time.

func (*TM) DoNext

func (tm *TM) DoNext(id TxId)

DoNext executes the operation specified in SetNext. It must be called after database changes have been committed.

func (*TM) End

func (tm *TM) End(id TxId) error

End terminates and forgets the transaction.

func (*TM) Recover

func (tm *TM) Recover(mgrs ...RM) error

Recover reads and processes the redo log, to complete interrupted transactions after a server restart.

func (*TM) SetNext

func (tm *TM) SetNext(id TxId, rm RM, opType int, op Op) error

SetNext sets or updates the next operation for an extended transaction. Database changes may have been requested, but must not be commmitted yet.

func (*TM) Timeout

func (tm *TM) Timeout(rm RM, opType int, before time.Time) error

Timeout executes any old operations for a resource manager. A non-zero opType selects the specified type.

type TxId

type TxId int64

Extended transaction identifier

func Id

func Id(s string) (TxId, error)

Id returns a transaction identifier from its string reresentation.