pig - v0.5.0

pig/obs/consumer_spec

Consumer specifications and owned consumer endpoints.

A StartedConsumer is the narrow endpoint the dispatcher needs: it can deliver a SessionEvent and it can be stopped by its owner. Keeping both operations together prevents startup code from losing the process handle that it must clean up on a later failure.

Types

ConsumerSpec

</>

A deferred consumer specification.

pub type ConsumerSpec {
  ConsumerSpec(
    spec: supervision.ChildSpecification(Nil),
    name: process.Name(SupervisedMessage),
    start_fn: fn() -> Result(StartedConsumer, actor.StartError),
  )
}

Constructors

StartedConsumer

opaque </>

An owned endpoint for a started consumer.

The consumer owns the details of delivery and shutdown. In particular, a consumer does not need to expose its actor message type to the dispatcher.

pub opaque type StartedConsumer

StopError

</>

Errors returned when a consumer cannot acknowledge a graceful stop.

pub type StopError {
  StopTimeout
}

Constructors 

  • StopTimeout

SupervisedMessage

</>

A control message understood by consumers that are supervised by pig.

The consumer acknowledges the stop without exiting. The surrounding supervisor exits immediately after the acknowledgement, which avoids a permanent child being restarted during an orderly shutdown.

pub type SupervisedMessage {
  Event(events.SessionEvent)
  Stop(process.Subject(Nil))
}

Constructors

Values

child_spec

</> 
pub fn child_spec(
  entry: ConsumerSpec,
) -> supervision.ChildSpecification(Nil)

Return the child specification carried by a consumer entry.

consume

</> 
pub fn consume(
  consumer: StartedConsumer,
  event: events.SessionEvent,
) -> Nil

Deliver an event to a started consumer.

started

</> 
pub fn started(
  consume_fn: fn(events.SessionEvent) -> Nil,
  stop_fn: fn() -> Nil,
) -> StartedConsumer

Build a started consumer endpoint from delivery and shutdown operations.

This compatibility constructor is for consumers whose stop operation has no typed failure result. Use started_with_result when the caller can observe a stop acknowledgement.

started_with_result

</> 
pub fn started_with_result(
  consume_fn: fn(events.SessionEvent) -> Nil,
  stop_fn: fn() -> Result(Nil, StopError),
) -> StartedConsumer

Build a started consumer endpoint with an observable stop result.

stop

</> 
pub fn stop(consumer: StartedConsumer) -> Nil

Stop a started consumer, preserving the historical fire-and-forget API.

stop_with_result

</> 
pub fn stop_with_result(
  consumer: StartedConsumer,
) -> Result(Nil, StopError)

Stop a started consumer and return its acknowledgement result.

subject_endpoint

</> 
pub fn subject_endpoint(
  subject: process.Subject(events.SessionEvent),
) -> StartedConsumer

Adapt an unowned SessionEvent subject for dynamic dispatcher use.

The endpoint can deliver events, but has no ownership of the subject’s process and therefore has a no-op stop operation.

supervised_endpoint

</> 
pub fn supervised_endpoint(
  name: process.Name(SupervisedMessage),
) -> StartedConsumer

Adapt a named supervised consumer subject with a graceful stop operation.

supervised_endpoint_for

</> 
pub fn supervised_endpoint_for(
  entry: ConsumerSpec,
) -> StartedConsumer

Build the dispatcher endpoint carried by a consumer entry.

supervised_spec

</> 
pub fn supervised_spec(
  spec: supervision.ChildSpecification(Nil),
  name: process.Name(SupervisedMessage),
  start_fn: fn() -> Result(StartedConsumer, actor.StartError),
) -> ConsumerSpec

Build a consumer specification with a gracefully controllable supervised endpoint.

✨ Search Document