Broadway v0.6.0-rc.0 Broadway.Message View Source

This struct holds all information about a message.

A message is first created by the producers. It is then sent downstream and gets updated multiple times, either by a module implementing the Broadway behaviour through the Broadway.handle_message/3 callback or internally by one of the built-in stages of Broadway.

Instead of modifying the struct directly, you should use the functions provided by this module to manipulate messages.

Link to this section Summary

Functions

Immediately acknowledges the given message or list of messages.

Configures the acknowledger of this message.

Mark a message as failed.

Defines the message batch key.

Sets the batching mode for the message.

Defines the target batcher which the message should be forwarded to.

Updates the data in a message.

Link to this section Types

Link to this type

t()

View Source
t() :: %Broadway.Message{
  acknowledger: {module(), ack_ref :: term(), data :: term()},
  batch_key: term(),
  batch_mode: :bulk | :flush,
  batcher: atom(),
  data: term(),
  metadata: %{optional(atom()) => term()},
  status:
    :ok
    | {:failed, reason :: binary()}
    | {:throw | :error | :exit, term(), Exception.stacktrace()}
}

Link to this section Functions

Link to this function

ack_immediately(message_or_messages)

View Source
ack_immediately(message :: t()) :: t()
ack_immediately(messages :: [t(), ...]) :: [t(), ...]

Immediately acknowledges the given message or list of messages.

This function can be used to acknowledge a message (or list of messages) immediately without waiting for the rest of the pipeline.

Acknowledging a message sets that message's acknowledger to a no-op acknowledger so that it's safe to ack at the end of the pipeline.

Returns the updated acked message if a message is passed in, or the updated list of acked messages if a list of messages is passed in.

Link to this function

configure_ack(message, options)

View Source
configure_ack(message :: t(), options :: keyword()) :: t()

Configures the acknowledger of this message.

This function calls the Broadway.Acknowledger.configure/3 callback to change the configuration of the acknowledger for the given message.

This function can only be called if the acknowledger implements the configure/3 callback. If it doesn't, an error is raised.

Link to this function

failed(message, reason)

View Source
failed(message :: t(), reason :: term()) :: t()

Mark a message as failed.

Failed messages are sent directly to the related acknowledger so they're not forwarded to the next step in the pipeline.

Link to this function

put_batch_key(message, batch_key)

View Source
put_batch_key(message :: t(), batch_key :: term()) :: t()

Defines the message batch key.

Batcher functions then attempt to create batches with the same batch_key, of size batch_size within period batch_timeout.

Link to this function

put_batch_mode(message, mode)

View Source
put_batch_mode(message :: t(), mode :: :bulk | :flush) :: t()

Sets the batching mode for the message.

When the mode is :bulk, the batch that the message is in is delivered after the batch size or batch timeout is reached.

When the mode is :flush, the batch that the message is in is delivered immediately after processing. Note it doesn't mean the batch contains only a single element but rather that all messages received from the processor are delivered without waiting.

The default mode for messages is :bulk.

Link to this function

put_batcher(message, batcher)

View Source
put_batcher(message :: t(), batcher :: atom()) :: t()

Defines the target batcher which the message should be forwarded to.

Link to this function

update_data(message, fun)

View Source
update_data(message :: t(), fun :: (term() -> term())) :: t()

Updates the data in a message.

This function is usually used inside the Broadway.handle_message/3 implementation to replace data with new processed data.