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(tx TxId) string
• func Timestamp(tx 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) AddNext(tx TxId, rm RM, opType int, op Op) error
  • func (tm *TM) AddTimed(tx TxId, rm RM, opType int, op Op, after time.Duration) error
  • func (tm *TM) Begin() TxId
  • func (tm *TM) Do(tx TxId) error
  • func (tm *TM) End(txId TxId) error
  • func (tm *TM) Forget(tx TxId, rm RM, opType int) error
  • func (tm *TM) Recover(mgrs ...RM) error
• type TxId
  • func Id(s string) (TxId, error)

Functions

func String

func String(tx TxId) string

String returns a formatted a transaction number. The string is reversed so that file names contructed from ID do not look similar.

func Timestamp

func Timestamp(tx 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)
}

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(tx TxId, opType int, op Op) // operation for execution, to be executed in current goroutine
}

RM is the interface for a resource manager, which implements operations.

type Redo

type Redo struct {
	Id        int64  // operation ID
	Tx        int64  // transaction ID
	Manager   string // resource manager name
	RedoType  int    // transaction manager's type
	Delay     int    // timed delay, in seconds
	OpType    int    // operation type
	Operation []byte // operation arguments, in JSON
}

Redo struct holds the stored data for a V2 transaction operation.

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 V2 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 non-volatile state of its own.

func New

func New(app App, store RedoStore) *TM

New returns an initialised transaction manager.

func (*TM) AddNext

func (tm *TM) AddNext(tx TxId, rm RM, opType int, op Op) error

AddNext adds an operation to the extended transaction, to be executed after the previous one. Database changes may have been requested, but must not be commmitted yet.

func (*TM) AddTimed

func (tm *TM) AddTimed(tx TxId, rm RM, opType int, op Op, after time.Duration) error

AddTimed adds an operation to the extended transaction, to be executed after the specified delay. The delay time has a resolution of one minute, and a maximum of 90 days.

func (*TM) Begin

func (tm *TM) Begin() TxId

Begin returns the ID for a new extended transaction.

func (*TM) Do

func (tm *TM) Do(tx TxId) error

Do executes the operations specified by AddNext(). It is called to start the first operation and after the completion of each asyncronous operation. It must be called after database changes have been committed.

func (*TM) End

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

End terminates and forgets an operation. It must be called by each RM.Operation, synchronously or asynchronously, in the context of a RedoStore transaction.

func (*TM) Forget

func (tm *TM) Forget(tx TxId, rm RM, opType int) error

Forget discards all operations of a specified type in a transaction as not needed.

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.

type TxId

type TxId int64

Extended transaction identifier

func Id

func Id(s string) (TxId, error)

Id returns a transaction identifier from its string representation.