Packmatic.Event (Packmatic v1.2.0) View Source

Represents Events that can be raised during the lifecycle of a Packmatic Stream being consumed.

To listen for Events, you must pass a function reference to the on_event: option when calling Packmatic.build_stream/2. This function will be called at appropriate junctures in the lifecycle of a Stream being consumed.

The Events will be called in the following order:

  1. Packmatic.Event.StreamStarted: Sent when the Stream starts encoding.

  2. Packmatic.Event.EntryStarted: Sent when the Stream starts encoding data for a new entry.

  3. Packmatic.Event.EntryUpdated: Sent when the entry has initialised and some data has been read. This event will be sent on each iteration of Packmatic.Source.read/1.

  4. Packmatic.Event.EntryFailed: Sent when the entry has failed to initialise (its Source returned an error during Packmatic.Source.init/1), in which case there would have been no EntryUpdated events, or when the entry has failed during the course of reading (its Source returned an error during Packmatic.Source.read/1).

  5. Packmatic.Event.EntryCompleted: Sent when the entry has been fully encoded (its Source has returned EOF).

  6. Packmatic.Event.StreamEnded: Sent when the Stream has completed journaling.

Please note that more event types may be added in the future.

Link to this section Summary

Types

Represents an Event that will be passed to the handler.

Represents the callback function passed to the Encoder.

Link to this section Types

Specs

Represents an Event that will be passed to the handler.

Specs

handler_fun() :: (event() -> :ok | no_return())

Represents the callback function passed to the Encoder.

The callback function takes 1 argument, which is the actual Event that is raised by Packmatic. The Event, event/0, is one of the pre-defined structs under the Packmatic.Event namespace.

Please keep in mind that more events may be added in the future, so you should always include a fallback clause in your handler function.

Handlers are called from the same process that the Stream is being iterated from, which allows you to control what happens to it. Should you not wish to interrupt the Encoder, return :ok. Otherwise, if you must, you may raise an exception, which will crash the Stream.