beehive - v1.0.0

hive

Types

Builder

opaque </>

The builder for a pool containing its configuration.

pub opaque type Builder(state, message)

DispatcherMessage

opaque </>

(internal) The message that can be sent to the dispatcher.

pub opaque type DispatcherMessage(message)

Next

opaque </>

(internal) The result of a worker after processing a message. Same as actor.Next but for hive.

pub opaque type Next(state)

SchedulingError

</>

The errors that can occur when scheduling a message to be processed by the pool.

pub type SchedulingError {
  CapacityExceeded
  FailedToStartWorker(cause: actor.StartError)
}

Constructors 

  • CapacityExceeded

    The pool has reached its maximum capacity and cannot accept any more messages.

  • FailedToStartWorker(cause: actor.StartError)

    The worker failed to start. This can happen if the worker’s initialiser function returns an error or if it fails to initialise within the given timeout.

Strategy

</> 
pub type Strategy {
  FirstInFirstOut
  LastInFirstOut
  OldestInFirstOut
}

Constructors 

  • FirstInFirstOut

    The first worker that was added to the free workers queue will be the first to be assigned a message.

  • LastInFirstOut

    The last worker that was added to the free workers queue will be the first to be assigned a message.

  • OldestInFirstOut

    The worker that has been alive for the longest will be the first to be assigned a message.

Values

continue

</> 
pub fn continue(state: state) -> Next(state)

Continue processing with the updated state

new

</> 
pub fn new(initial: state) -> Builder(state, message)

Create a new builder with the given initial state. The default size will be 1 and strategy is FIFO.

new_with_initialiser

</> 
pub fn new_with_initialiser(
  timeout: Int,
  initialiser: fn(process.Subject(message)) -> Result(
    state,
    String,
  ),
) -> Builder(state, message)

Create a new builder with the given initialiser function and timeout for the initialiser. The default size will be 1 and strategy is FIFO.

If the worker does not initialise within the given timeout, the message will be rejected and an error will be returned from the send function.

on_message

</> 
pub fn on_message(
  builder: Builder(state, message),
  on_message: fn(state, message) -> Next(state),
) -> Builder(state, message)

Set the handler for processing messages.

send

</> 
pub fn send(
  subject: process.Subject(DispatcherMessage(message)),
  message: message,
  timeout: Int,
) -> Result(Nil, SchedulingError)

Send a message to any available worker in the pool. If all workers are busy and the pool has reached its maximum capacity or if the worker fails to start, an error will be returned.

The timeout represents the maximum amount of time (in ms) to wait for a worker to start. If the worker does not start within the given timeout, an error will be returned.

stop

</> 
pub fn stop() -> Next(state)

Stop processing and terminate the worker normally

stop_abnormal

</> 
pub fn stop_abnormal(reason: String) -> Next(state)

Stop processing and terminate the worker abnormally with the given reason

supervised

</> 
pub fn supervised(
  builder: Builder(state, message),
) -> supervision.ChildSpecification(static_supervisor.Supervisor)

Create the child specification for the pool to be started under a supervisor.

with_close_after

</> 
pub fn with_close_after(
  builder: Builder(state, message),
  close_after: Int,
) -> Builder(state, message)

Set the maximum amount of time (in ms) a worker can be idle before it is stopped. If not set, workers will never be stopped automatically.

with_event_receiver

</> 
pub fn with_event_receiver(
  builder: Builder(state, message),
  event_receiver: process.Subject(event.EventMessage),
) -> Builder(state, message)

Set the subject that should receive events emitted by the pool. This is primarily for testing purposes.

with_name

</> 
pub fn with_name(
  builder: Builder(state, message),
  name: process.Name(DispatcherMessage(message)),
) -> Builder(state, message)

Set the name of the pool. This is required to send messages to the pool when started under a supervisor.

with_processing_timeout

</> 
pub fn with_processing_timeout(
  builder: Builder(state, message),
  processing_timeout: Int,
) -> Builder(state, message)

Set the maximum amount of time (in ms) a worker can take to process a message before it is considered to have failed. If not set, workers will never be considered to have failed due to taking too long to process a message.

with_queue

</> 
pub fn with_queue(
  builder: Builder(state, message),
  queue_builder: queue.Builder,
) -> Builder(state, message)

with_size

</> 
pub fn with_size(
  builder: Builder(state, message),
  size: Int,
) -> Builder(state, message)

Set the maximum number of workers in the pool.

with_strategy

</> 
pub fn with_strategy(
  builder: Builder(state, message),
  strategy: Strategy,
) -> Builder(state, message)

Set the strategy for scheduling messages to workers in the pool.

✨ Search Document