events

Documentation

Index

• Constants
• type CheckFunc
• type EventHandler
• type EventHelperAPI
• type Events
  • func NewEvents(ctx context.Context, api EventHelperAPI) (*Events, error)
  • func (e Events) ChainAt(ctx context.Context, hnd HeightHandler, rev RevertHandler, confidence int, ...) error
  • func (o Events) Observe(obs TipSetObserver) *types.TipSet
  • func (o Events) ObserveAndBlock(obs TipSetObserver) (*types.TipSet, func(), error)
  • func (o Events) Unregister(obs TipSetObserver) (found bool)
• type HeightHandler
• type MsgHandler
• type MsgMatchFunc
• type RevertHandler
• type StateChange
• type StateChangeHandler
• type StateMatchFunc
• type TipSetObserver

Constants

const NoHeight = abi.ChainEpoch(-1)

const NoTimeout = math.MaxInt64

Types

type CheckFunc

type CheckFunc func(ctx context.Context, ts *types.TipSet) (done bool, more bool, err error)

CheckFunc is used for atomicity guarantees. If the condition the callbacks wait for has already happened in tipset `ts`

If `done` is true, timeout won't be triggered If `more` is false, no messages will be sent to EventHandler (RevertHandler

may still be called)

type EventHandler

type EventHandler func(ctx context.Context, data eventData, prevTs, ts *types.TipSet, curH abi.ChainEpoch) (more bool, err error)

EventHandler arguments: `prevTs` is the previous tipset, eg the "from" tipset for a state change. `ts` is the event tipset, eg the tipset in which the `msg` is included. `curH`-`ts.Height` = `confidence`

type EventHelperAPI

type EventHelperAPI interface {
	ChainNotify(context.Context) (<-chan []*api.HeadChange, error)
	ChainGetBlockMessages(context.Context, cid.Cid) (*api.BlockMessages, error)
	ChainGetTipSetByHeight(context.Context, abi.ChainEpoch, types.TipSetKey) (*types.TipSet, error)
	ChainGetTipSetAfterHeight(context.Context, abi.ChainEpoch, types.TipSetKey) (*types.TipSet, error)
	ChainHead(context.Context) (*types.TipSet, error)
	StateSearchMsg(ctx context.Context, from types.TipSetKey, msg cid.Cid, limit abi.ChainEpoch, allowReplaced bool) (*api.MsgLookup, error)
	ChainGetTipSet(context.Context, types.TipSetKey) (*types.TipSet, error)
	ChainGetPath(ctx context.Context, from, to types.TipSetKey) ([]*api.HeadChange, error)

	StateGetActor(ctx context.Context, actor address.Address, tsk types.TipSetKey) (*types.Actor, error) // optional / for CalledMsg
}

type Events

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

func NewEvents

func NewEvents(ctx context.Context, api EventHelperAPI) (*Events, error)

func (Events) ChainAt

func (e Events) ChainAt(ctx context.Context, hnd HeightHandler, rev RevertHandler, confidence int, h abi.ChainEpoch) error

ChainAt invokes the specified `HeightHandler` when the chain reaches the specified height+confidence threshold. If the chain is rolled-back under the specified height, `RevertHandler` will be called.

ts passed to handlers is the tipset at the specified epoch, or above if lower tipsets were null.

The context governs cancellations of this call, it won't cancel the event handler.

func (Events) Observe

func (o Events) Observe(obs TipSetObserver) *types.TipSet

Observe registers the observer, and returns the current tipset. The observer is guaranteed to observe events starting at this tipset.

Returns nil if the observer hasn't started yet (but still registers).

func (Events) ObserveAndBlock

func (o Events) ObserveAndBlock(obs TipSetObserver) (*types.TipSet, func(), error)

ObserveAndBlock registers the observer and returns the current tipset along with an unlock function.

This method guarantees that the observer will receive tipset updates starting from the returned tipset. It blocks all tipset updates for all clients until the returned unlock function is called.

The typical usage pattern is: 1. Call ObserveAndBlock to register the observer 2. Perform any necessary initialization using the returned current tipset 3. Call the unlock function to start receiving updates

Important notes: - This method should only be called after the observer has been started - The unlock function must be called to prevent blocking of tipset updates for all registered observers - This method returns an error if the observer hasn't started yet

Returns: - *types.TipSet: The current tipset at the time of registration - func(): An unlock function that must be called to start receiving updates - error: An error if the observer hasn't started yet

func (Events) Unregister

func (o Events) Unregister(obs TipSetObserver) (found bool)

Unregister unregisters an observer. Returns true if we successfully removed the observer.

NOTE: The observer _may_ be called after being removed. Observers MUST handle this case internally.

type HeightHandler

type HeightHandler func(ctx context.Context, ts *types.TipSet, curH abi.ChainEpoch) error

HeightHandler `curH`-`ts.Height` = `confidence`

type MsgHandler

type MsgHandler func(msg *types.Message, rec *types.MessageReceipt, ts *types.TipSet, curH abi.ChainEpoch) (more bool, err error)

MsgHandler arguments: `ts` is the tipset, in which the `msg` is included. `curH`-`ts.Height` = `confidence`

type MsgMatchFunc

type MsgMatchFunc func(msg *types.Message) (matched bool, err error)

type RevertHandler

type RevertHandler func(ctx context.Context, ts *types.TipSet) error

type StateChange

type StateChange interface{}

StateChange represents a change in state

type StateChangeHandler

type StateChangeHandler func(oldTs, newTs *types.TipSet, states StateChange, curH abi.ChainEpoch) (more bool, err error)

StateChangeHandler arguments: `oldTs` is the state "from" tipset `newTs` is the state "to" tipset `states` is the change in state `curH`-`ts.Height` = `confidence`

type StateMatchFunc

type StateMatchFunc func(oldTs, newTs *types.TipSet) (bool, StateChange, error)

type TipSetObserver

type TipSetObserver interface {
	Apply(ctx context.Context, from, to *types.TipSet) error
	Revert(ctx context.Context, from, to *types.TipSet) error
}

A TipSetObserver receives notifications of tipsets