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 StringV1(tx TxId) string
• func Timestamp(tx TxId) time.Time
• type App
• type Op
• type RM
• type Redo
• type RedoStore
• type RedoStoreV1
• type RedoV1
• 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) BeginNext(first TxId, rm RM, opType int, op Op) error
  • func (tm *TM) Do(tx TxId) error
  • func (tm *TM) DoNext(id TxId)
  • 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
  • func (tm *TM) RecoverV1(store RedoStoreV1, mgrs ...RM) error
  • func (tm *TM) SetNext(id TxId, rm RM, opType int, op Op) error
  • func (tm *TM) TimeoutV1(rm RM, opType int, before time.Time) 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 StringV1

func StringV1(tx TxId) string

String returns a formatted a transaction number, for names that were not reversed.

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 RedoStoreV1

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

RedoStoreV1 is the interface for storage of V1 extended transactions, implemented by the parent application.

type RedoV1

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

Redo struct holds the stored data for a V1 transaction 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 initialises the 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) BeginNext

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

Deprecated from V1 as a misleading name. Use the equivalent TM.AddNext instead.

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) DoNext

func (tm *TM) DoNext(id TxId)

Deprecated from V1 as a misleading name. Use the equivalent TM.Do instead.

func (*TM) End

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

End terminates and forgets the current operation.

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.

func (*TM) RecoverV1

func (tm *TM) RecoverV1(store RedoStoreV1, mgrs ...RM) error

RecoverV1 reads and processes the V1 redo log, to complete any interrupted transactions from before server upgrade and restart.

func (*TM) SetNext

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

Deprecated from V1 as too general. Use TM.AddNext in most cases, with TM.Forget+TM.AddNext to modify an existing operation.

func (*TM) TimeoutV1

func (tm *TM) TimeoutV1(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 representation.