package delivery
- Alphabetic
- Public
- Protected
Value Members
- object ConsumerController
ConsumerController
and ProducerController or WorkPullingProducerController are used together.ConsumerController
and ProducerController or WorkPullingProducerController are used together. See the descriptions in those classes or the Pekko reference documentation for how they are intended to be used.The destination consumer actor will start the flow by sending an initial ConsumerController.Start message to the
ConsumerController
. TheActorRef
in theStart
message is typically constructed as a message adapter to map the ConsumerController.Delivery to the protocol of the consumer actor.Received messages from the producer are wrapped in ConsumerController.Delivery when sent to the consumer, which is supposed to reply with ConsumerController.Confirmed when it has processed the message. Next message is not delivered until the previous is confirmed. More messages from the producer that arrive while waiting for the confirmation are stashed by the
ConsumerController
and delivered when previous message was confirmed.The consumer and the
ConsumerController
actors are supposed to be local so that these messages are fast and not lost. This is enforced by a runtime check.The
ConsumerController
is automatically stopped when the consumer that registered with theStart
message is terminated.- Annotations
- @ApiMayChange()
- object DurableProducerQueue
Actor message protocol for storing and confirming reliable delivery of messages.
Actor message protocol for storing and confirming reliable delivery of messages. A pekko.actor.typed.Behavior implementation of this protocol can optionally be used with ProducerController when messages shall survive a crash of the producer side.
An implementation of this exists in
org.apache.pekko.persistence.typed.delivery.EventSourcedProducerQueue
.- Annotations
- @ApiMayChange()
- object ProducerController
Point-to-point reliable delivery between a single producer actor sending messages and a single consumer actor receiving the messages.
Point-to-point reliable delivery between a single producer actor sending messages and a single consumer actor receiving the messages. Used together with ConsumerController.
The producer actor will start the flow by sending a ProducerController.Start message to the
ProducerController
. TheActorRef
in theStart
message is typically constructed as a message adapter to map the ProducerController.RequestNext to the protocol of the producer actor.For the
ProducerController
to know where to send the messages it must be connected with theConsumerController
. You do this is with ProducerController.RegisterConsumer or ConsumerController.RegisterToProducerController messages.The
ProducerController
sendsRequestNext
to the producer, which is then allowed to send one message to theProducerController
via thesendNextTo
in theRequestNext
. Thereafter the producer will receive a newRequestNext
when it's allowed to send one more message.The producer and
ProducerController
actors are supposed to be local so that these messages are fast and not lost. This is enforced by a runtime check.Many unconfirmed messages can be in flight between the
ProducerController
andConsumerController
. The flow control is driven by the consumer side, which means that theProducerController
will not send faster than the demand requested by theConsumerController
.Lost messages are detected, resent and deduplicated if needed. This is also driven by the consumer side, which means that the
ProducerController
will not push resends unless requested by theConsumerController
.Until sent messages have been confirmed the
ProducerController
keeps them in memory to be able to resend them. If the JVM of theProducerController
crashes those unconfirmed messages are lost. To make sure the messages can be delivered also in that scenario theProducerController
can be used with a DurableProducerQueue. Then the unconfirmed messages are stored in a durable way so that they can be redelivered when the producer is started again. An implementation of theDurableProducerQueue
is provided byEventSourcedProducerQueue
inpekko-persistence-typed
.Instead of using
tell
with thesendNextTo
in theRequestNext
the producer can usecontext.ask
with theaskNextTo
in theRequestNext
. The difference is that a reply is sent back when the message has been handled. If aDurableProducerQueue
is used then the reply is sent when the message has been stored successfully, but it might not have been processed by the consumer yet. Otherwise the reply is sent after the consumer has processed and confirmed the message.If the consumer crashes a new
ConsumerController
can be connected to the originalProducerConsumer
without restarting it. TheProducerConsumer
will then redeliver all unconfirmed messages.It's also possible to use the
ProducerController
andConsumerController
without resending lost messages, but the flow control is still used. This can for example be useful when both consumer and producer are know to be located in the same localActorSystem
. This can be more efficient since messages don't have to be kept in memory in theProducerController
until they have been confirmed, but the drawback is that lost messages will not be delivered. See configurationonly-flow-control
of theConsumerController
.The
producerId
is used in logging and included as MDC entry with key"producerId"
. It's propagated to theConsumerController
and is useful for correlating log messages. It can be anyString
but it's recommended to use a unique identifier of representing the producer.If the
DurableProducerQueue
is defined it is created as a child actor of theProducerController
actor. It will use the same dispatcher as the parentProducerController
.- Annotations
- @ApiMayChange()
- object WorkPullingProducerController
Work pulling is a pattern where several worker actors pull tasks in their own pace from a shared work manager instead of that the manager pushes work to the workers blindly without knowing their individual capacity and current availability.
Work pulling is a pattern where several worker actors pull tasks in their own pace from a shared work manager instead of that the manager pushes work to the workers blindly without knowing their individual capacity and current availability.
The
WorkPullingProducerController
can be used together with ConsumerController to implement the work pulling pattern.One important property is that the order of the messages should not matter, because each message is routed randomly to one of the workers with demand. In other words, two subsequent messages may be routed to two different workers and processed independent of each other.
A worker actor (consumer) and its
ConsumerController
is dynamically registered to theWorkPullingProducerController
via a pekko.actor.typed.receptionist.ServiceKey. It will register itself to the * pekko.actor.typed.receptionist.Receptionist, and theWorkPullingProducerController
subscribes to the same key to find active workers. In this way workers can be dynamically added or removed from any node in the cluster.The work manager (producer) actor will start the flow by sending a WorkPullingProducerController.Start message to the
WorkPullingProducerController
. TheActorRef
in theStart
message is typically constructed as a message adapter to map the WorkPullingProducerController.RequestNext to the protocol of the producer actor.The
WorkPullingProducerController
sendsRequestNext
to the producer, which is then allowed to send one message to theWorkPullingProducerController
via thesendNextTo
in theRequestNext
. Thereafter the producer will receive a newRequestNext
when it's allowed to send one more message. It will send a newRequestNext
when there are demand from any worker. It's possible that all workers with demand are deregistered after theRequestNext
is sent and before the actual messages is sent to theWorkPullingProducerController
. In that case the message is buffered and will be delivered when a new worker is registered or when there is new demand.The producer and
WorkPullingProducerController
actors are supposed to be local so that these messages are fast and not lost. This is enforced by a runtime check.Many unconfirmed messages can be in flight between the
WorkPullingProducerController
and eachConsumerController
. The flow control is driven by the consumer side, which means that theWorkPullingProducerController
will not send faster than the demand requested by the workers.Lost messages are detected, resent and deduplicated if needed. This is also driven by the consumer side, which means that the
WorkPullingProducerController
will not push resends unless requested by theConsumerController
.If a worker crashes or is stopped gracefully the unconfirmed messages for that worker will be routed to other workers by the
WorkPullingProducerController
. This may result in that some messages may be processed more than once, by different workers.Until sent messages have been confirmed the
WorkPullingProducerController
keeps them in memory to be able to resend them. If the JVM of theWorkPullingProducerController
crashes those unconfirmed messages are lost. To make sure the messages can be delivered also in that scenario theWorkPullingProducerController
can be used with a DurableProducerQueue. Then the unconfirmed messages are stored in a durable way so that they can be redelivered when the producer is started again. An implementation of theDurableProducerQueue
is provided byEventSourcedProducerQueue
inpekko-persistence-typed
.Instead of using
tell
with thesendNextTo
in theRequestNext
the producer can usecontext.ask
with theaskNextTo
in theRequestNext
. The difference is that a reply is sent back when the message has been handled. If aDurableProducerQueue
is used then the reply is sent when the message has been stored successfully, but it might not have been processed by the consumer yet. Otherwise the reply is sent after the consumer has processed and confirmed the message.It's also possible to use the
WorkPullingProducerController
andConsumerController
without resending lost messages, but the flow control is still used. This can for example be useful when both consumer and producer are know to be located in the same localActorSystem
. This can be more efficient since messages don't have to be kept in memory in theProducerController
until they have been confirmed, but the drawback is that lost messages will not be delivered. See configurationonly-flow-control
of theConsumerController
.The
producerId
is used in logging and included as MDC entry with key"producerId"
. It's propagated to theConsumerController
and is useful for correlating log messages. It can be anyString
but it's recommended to use a unique identifier of representing the producer.If the
DurableProducerQueue
is defined it is created as a child actor of theWorkPullingProducerController
actor.ProducerController
actors are created for each registered worker. Those child actors use the same dispatcher as the parentWorkPullingProducerController
.- Annotations
- @ApiMayChange()