Register an unsupervised handler with the event manager.

Returns Ok(HandlerRef) on success. The returned ref uniquely identifies this handler instance and can be used with remove_handler.

If the handler crashes, the manager removes it silently without notifying the caller. For crash notifications use add_supervised_handler.

Example

case event_manager.add_handler(manager, my_handler) {
  Ok(handler_ref) -> // use handler_ref later with remove_handler
  Error(_) -> Nil
}

Register a supervised handler with the event manager.

Like add_handler, but links the handler to the calling process. If the handler is removed for any reason other than a normal remove_handler call (e.g. it crashes or returns Remove), the calling process receives an Erlang message shaped like:

{gen_event_EXIT, HandlerRef, Reason}

Receive it via gleam/erlang/process selectors — process.select_other is the catch-all hook you can use to observe raw Erlang messages.

Non-blocking check: inspect message to see if it is a reply for request_id.

Useful inside a custom process.Selector receive loop. Pass any message you receive; if it does not belong to this request CheckNoReply is returned and the message is left for other handlers.

Example

case event_manager.check_response(raw_msg, req) {
  event_manager.CheckGotReply(value) -> // handle value
  event_manager.CheckNoReply -> // not ours, pass it on
  event_manager.CheckCrashed(reason) -> // handle error
}

Non-blocking check: inspect message to see whether it is a reply for any request in collection.

Returns GotReply(...) / RequestFailed(...) if the message belongs to the collection, NoReply(remaining) if it is unrelated, or NoRequests if the collection is empty. Never blocks.

Example

case event_manager.check_response_collection(raw_msg, coll, event_manager.Delete) {
  event_manager.GotReply(value, label, rest) -> // handle and continue
  event_manager.NoReply(_) -> // not ours, pass it on
  _ -> // ...
}

Requires Erlang/OTP 25.0 or later.

Return the Pid of the event manager process.

Useful for monitoring the manager with process.monitor when you did not start it via start_monitor.

Handler Builder

Create a handler with an initial state and an event callback.

The on_event function is called for every event delivered to this handler via notify or sync_notify. It receives the event and the current state, and must return either Continue(new_state) or Remove.

Example

let handler =
  event_manager.new_handler(initial_state: 0, on_event: fn(event, count) {
    case event {
      Increment -> event_manager.Continue(count + 1)
      Reset     -> event_manager.Continue(0)
    }
  })

Build a fresh StartOptions with defaults: no registered name, Infinity for both timeout and hibernate_after, no debug flags, no spawn options.

Asynchronously broadcast an event to all registered handlers.

Returns immediately without waiting for handlers to finish processing. Use sync_notify if you need a synchronization point.

Provide a function to format this handler’s state for OTP status reports.

When set, the returned string is used in place of the raw state in sys:get_status/1 output and SASL crash reports. Useful for hiding secrets, summarising large data structures, or presenting a domain-friendly view. Since OTP 25.0.

Example

event_manager.new_handler(connection, on_event)
|> event_manager.on_format_status(fn(connection) {
  "Conn(id=" <> connection.id <> ")"
})

Derive this handler’s initial state from the value produced by the previous handler’s on_swap_out during a swap_handler operation.

When this callback is unset, the handler’s init_state is used as-is and any value produced by the previous handler is discarded.

Example

event_manager.new_handler(0, on_event)
|> event_manager.on_swap_in(fn(term) {
  case event_manager.swap_term_decode(term, decode.int) {
    Ok(n) -> n
    Error(_) -> 0
  }
})

Provide a value to hand to the next handler when this one is swapped out via swap_handler or swap_supervised_handler.

The function receives the current handler state and returns a SwapTerm (built with swap_term_from) that the next handler’s on_swap_in can decode. When unset, the next handler’s on_swap_in (if any) is invoked with a placeholder value.

This callback is invoked instead of on_terminate when the removal happens through a swap. If you need both cleanup and state transfer in the swap path, run the cleanup inline within on_swap_out.

Example

event_manager.new_handler(0, on_event)
|> event_manager.on_swap_out(fn(count) { event_manager.swap_term_from(count) })

Attach a cleanup function called when the handler is removed or the manager stops.

Example

event_manager.new_handler(connection, on_event)
|> event_manager.on_terminate(fn(connection) { db.close(connection) })

Wait up to timeout milliseconds for the reply to a RequestId.

Returns Ok(reply) on success, Error(ReceiveTimeout) if no reply arrives in time, or Error(RequestCrashed(reason)) if the manager exited.

Wait up to timeout milliseconds for any pending reply in a collection.

Pass Delete to remove the matched request from the returned collection, or Keep to retain it. Call this in a loop to drain all responses one by one. Returns CollectionTimeout(remaining) when the timer expires before any reply arrives, and NoRequests when the collection is empty.

Selectively drains the matched message from the mailbox; non-matching mailbox messages may also be consumed.

Example

let assert event_manager.GotReply(value, label, collection) =
  event_manager.receive_response_collection(
    collection,
    1000,
    event_manager.Delete,
  )

Requires Erlang/OTP 25.0 or later.

Remove a specific handler from the event manager.

The handler’s on_terminate callback is called before removal.

Add a RequestId to a collection under a label.

The label is returned alongside the reply in receive_response_collection, letting you identify which request the response belongs to.

Requires Erlang/OTP 25.0 or later.

Create a new, empty request-id collection.

Used with send_request_to_collection to batch multiple async requests and then drain them through receive_response_collection (or similar).

Requires Erlang/OTP 25.0 or later.

Return the number of pending request IDs in a collection.

Requires Erlang/OTP 25.0 or later.

Convert a collection to a list of #(RequestId, label) pairs.

Requires Erlang/OTP 25.0 or later.

Asynchronously call a specific handler and return a RequestId.

Unlike sync_notify, this targets one handler by its HandlerRef and expects a reply. The handler must have been registered with with_call_handler set; otherwise receive_response will return Error(RequestCrashed(_)).

Use receive_response or wait_response to collect the reply later, or check_response to poll non-blockingly.

Example

let req: event_manager.RequestId(Int) =
  event_manager.send_request(mgr, handler_ref, GetCount)
// ... do other work ...
let assert Ok(count) = event_manager.receive_response(req, 1000)

Send an asynchronous call to a specific handler and immediately add the resulting RequestId to a collection under the given label.

Equivalent to calling send_request and request_ids_add in one step. Useful for issuing several requests in a loop before waiting for any of them.

Example

let collection: event_manager.RequestIdCollection(String, Int) =
  event_manager.request_ids_new()
let collection =
  event_manager.send_request_to_collection(mgr, h1, GetCount, "h1", collection)
let collection =
  event_manager.send_request_to_collection(mgr, h2, GetCount, "h2", collection)
// ... drain via receive_response_collection ...

Requires Erlang/OTP 25.0 or later.

Start an event manager process without linking it to the caller.

Maps to gen_event:start/1,2. Useful when the parent does not want link-based crash propagation, e.g. when the parent will install its own monitor or hand the manager to a custom supervisor.

Start an event manager process linked to the caller.

Maps to gen_event:start_link/1,2. Use with_name on the options to register the manager under a Local, Global, or Via name; otherwise the manager is started anonymously.

Example

case event_manager.start_link(event_manager.new_start_options()) {
  Ok(manager) -> {
    // ... use manager ...
    event_manager.stop(manager)
  }
  Error(_) -> Nil
}

Example: registered under a local name

let name = process.new_name("my_event_manager")
let options =
  event_manager.new_start_options()
  |> event_manager.with_name(event_manager.Local(name))
let assert Ok(manager) = event_manager.start_link(options)

Start an event manager linked to the caller and atomically return a monitor for it.

Equivalent to calling start_link(options) followed by process.monitor(manager_pid), but without the race window between the two calls. The returned MonitoredManager carries both the Manager and a process.Monitor you can select on. Since OTP 23.0.

Example

case event_manager.start_monitor(event_manager.new_start_options()) {
  Ok(monitored) -> {
    let selector =
      process.new_selector()
      |> process.select_specific_monitor(monitored.monitor, fn(down) { down })
    // ... use monitored.manager, wait on `selector` for a Down message ...
  }
  Error(_) -> Nil
}

Stop the event manager, terminating it with reason normal.

All registered handlers have their on_terminate callback invoked before the manager shuts down.

Atomically swap an installed handler for a new one.

Maps to gen_event:swap_handler/3. The old handler’s on_swap_out callback runs (if set), its result is threaded into the new handler’s on_swap_in (if set) to produce the new handler’s initial state, and the new handler is installed — all observed by the manager as a single transaction so no notify can slip between the remove and the add.

On success, returns the new handler’s HandlerRef. The old HandlerRef becomes invalid.

The new handler is unsupervised. Use swap_supervised_handler to link the new handler to the calling process.

Example

case event_manager.swap_handler(mgr, old_ref, new_handler) {
  Ok(new_ref) -> // use new_ref
  Error(_) -> Nil
}

Atomically swap an installed handler for a new supervised handler.

Like swap_handler, but maps to gen_event:swap_sup_handler/3: the new handler is linked to the calling process. If the new handler is later removed for any reason other than a normal remove_handler call, the caller receives a {gen_event_EXIT, HandlerRef, Reason} message.

Decode the value carried by a SwapTerm using a decode.Decoder, typically inside on_swap_in.

Example

event_manager.on_swap_in(fn(term) {
  case event_manager.swap_term_decode(term, decode.int) {
    Ok(n) -> n
    Error(_) -> 0
  }
})

Wrap any value as a SwapTerm to hand to the next handler from on_swap_out.

Synchronously broadcast an event to all registered handlers.

Blocks until every currently registered handler has processed the event. Use this when you need to know that all handlers have seen the event before continuing.

Wait up to timeout milliseconds for the reply to a RequestId.

Like receive_response, but maps to gen_event:wait_response/2. The two differ only in mailbox semantics: wait_response leaves non-matching messages in place on success, whereas receive_response selectively drains the matching message (and may leave the receive buffer in a state that affects later receive clauses).

Like receive_response_collection but maps to gen_event:wait_response/3.

On success, leaves non-matching mailbox messages in place rather than draining them. Use when integrating with a custom process.Selector that expects untouched non-matching messages.

Requires Erlang/OTP 25.0 or later.

Return the list of HandlerRefs for all currently registered handlers.

Attach a call handler to a handler, enabling async request/response via send_request. The on_call function receives the request and the current handler state, and must return a #(reply, new_state) tuple.

Without this, send_request calls to this handler will fail with Error(RequestCrashed(_)).

Example

event_manager.new_handler(0, on_event)
|> event_manager.with_call_handler(fn(GetCount, count) { #(count, count) })

Set the sys debug flags for the manager.

Set the idle hibernation timeout. Passed through to gen_event as the {hibernate_after, _} option.

Register the manager under a name when it starts.

Pass Local(name) for the common local-atom registration (the only form compatible with a process.Subject), Global(name) for cluster-wide registration via the global module, or Via(module, term) for a custom registry such as gproc or syn.

Set the erlang:spawn_opt/2 options forwarded to the manager process.

Set the initialisation timeout. Passed through to gen_event as the {timeout, _} option.