MakeSingle (octez-libs.Tezos_bees.Worker.MakeSingle)

Parameters

module Name : Tezos_base.Worker_intf.NAME

module Request : Tezos_base.Worker_intf.REQUEST

module Types : Tezos_base.Worker_intf.TYPES

Signature

module Name = Name

module Request = Request

module Types = Types

type 'kind t

A handle to a specific worker, parameterized by the type of internal message buffer.

type 'kind table

A handle to a table of workers.

type 'a queue

Internal buffer kinds used as parameters to t.

and bounded

and infinite

type dropbox

type scope

type metadata = {

scope : scope option;

}

type 'a message_error =

| Closed of Tezos_base.TzPervasives.error list option
| Request_error of 'a
| Any of exn

An error returned when waiting for a message pushed to the worker. Closed errs is returned if the worker is terminated or has crashed. If the worker is terminated, errs is an empty list. Request_error err is returned if the request failed with an error. Any exn is returned if the request failed with an exception.

type _ buffer_kind =

| Queue : infinite queue buffer_kind
| Bounded : {
1. size : int;
} -> bounded queue buffer_kind
| Dropbox : {
1. merge : dropbox t -> any_request -> any_request option -> any_request option;
} -> dropbox buffer_kind

Supported kinds of internal buffers.

and any_request =

| Any_request : (_, _) Request.t * metadata -> any_request

val create_table : 'kind buffer_kind -> 'kind table

Create a table of workers.

module type HANDLERS = sig ... end

The callback handlers specific to each worker instance.

val launch : 
  'kind table ->
  ?timeout:Tezos_base.Time.System.Span.t ->
  ?domains:int ->
  Name.t ->
  Types.parameters ->
  (module HANDLERS
    with type launch_error = 'launch_error
     and type self = 'kind t) ->
  ('kind t, 'launch_error) Stdlib.result Lwt.t

launch table name parameters handlers creates an instance of the worker, of the given queue kind. Requires callers to run inside Tezos_base_unix.Event_loop.main_run (or after the Event_loop main switch has been initialised), otherwise the worker initialisation will block while waiting for the main-domain scheduler.

val shutdown : _ t -> unit Lwt.t

Triggers a worker termination and waits for its completion. Cannot be called from within the handlers.

val shutdown_eio : _ t -> unit

module type BOX = sig ... end

The following interface are common elements of multiple modules below. They are used to minimize repetition.

module type QUEUE = sig ... end

module Dropbox : sig ... end

module Queue : sig ... end

val canceler : _ t -> Lwt_canceler.t

Exports the canceler to allow cancellation of other tasks when this worker is shutdown or when it dies.

val trigger_shutdown : _ t -> unit

Triggers a worker termination.

val state : _ t -> Types.state

Access the internal state, once initialized.

val with_state : 
  _ t ->
  (Types.state -> (unit, 'request_error) Stdlib.result Lwt.t) ->
  (unit, 'request_error) Stdlib.result Lwt.t

with_state w f calls f on the current state of worker w if it was intialized and not closed or crashed, otherwise returns immediately.

val with_state_eio : 
  _ t ->
  (Types.state -> (unit, 'request_error) Stdlib.result) ->
  (unit, 'request_error) Stdlib.result

val pending_requests : 
  _ queue t ->
  (Tezos_base.Time.System.t * Request.view) list

Introspect the message queue, gives the times requests were pushed.

val status : _ t -> Tezos_base.Worker_types.worker_status

Get the running status of a worker.

val current_request : 
  _ t ->
  (Tezos_base.Time.System.t * Tezos_base.Time.System.t * Request.view) option

Get the request being treated by a worker. Gives the time the request was pushed, and the time its treatment started.

val information : _ t -> Tezos_base.Worker_types.worker_information

val list : 'a table -> (Name.t * 'a t) list

Lists the running workers in this group.

val find_opt : 'a table -> Name.t -> 'a t option

find_opt table n is Some worker if the worker is in the table and has name n.

module type EIO_HANDLERS = sig ... end

EIO_HANDLERS is HANDLERS within the Eio event loop.

module MakeEIO
  (H : HANDLERS) : 
  EIO_HANDLERS with type self = H.self and type launch_error = H.launch_error

val launch_eio : 
  'kind table ->
  ?timeout:Tezos_base.Time.System.Span.t ->
  ?domains:int ->
  name:Name.t ->
  Types.parameters ->
  (module EIO_HANDLERS
    with type launch_error = 'launch_error
     and type self = 'kind t) ->
  ('kind t, 'launch_error) Stdlib.result

launch table name parameters handlers creates a swarm of bees (workers), each running on a separate domain. By default only a single domain (then worker) is used to handle the requests. As with launch, callers must ensure the Event_loop main switch has been started (typically via Tezos_base_unix.Event_loop.main_run) so that the worker initialisation scheduled on the main domain can complete.