chip - v1.0.0

chip

Chip is a local subject registry that can reference subjects individually or as part of a group. Will also automatically delist dead processes.

Types

Message

opaque </>

Chip’s internal message type.

pub opaque type Message(msg, group)

Named

</>

An option passed to chip.start to make the registry available through a name.

pub type Named {
  Named(String)
  Unnamed
}

Constructors 

  • Named(String)
  • Unnamed

Registry

</>

An shorter alias for the registry’s subject.

Sometimes, when building out your system it may be useful to state the Registry’s types.

Example

let assert Ok(registry) = chip.start(chip.Unnamed)
let registry: chip.Registry(Event, Topic)

Which is equivalent to:

let assert Ok(registry) = chip.start()
let registry: process.Subject(chip.Message(Event, Topic))

By specifying the types we can document the kind of registry we are working with.

pub type Registry(msg, group) =
  Subject(Message(msg, group))

Functions

from

</> 
pub fn from(name: String) -> Result(Subject(Message(a, b)), Nil)

Retrieves a previously named registry.

Example

let _ = chip.start(chip.Named("sessions"))
let assert Ok(registry) = chip.from("sessions")

This function can be useful when you don’t have the registry’s subject in scope. Ideally, you would carry around the registry’s subject down your pipeline and always have it available but this can become hard to mantains if you don’t already provide a solid solution for your system.

Be mindful that using it means you lose type safety as the from function only knows you return a registry but it doesn’t know the message type or the group type. It would not be a bad idea to wrap it under a typed function:

fn get_session(name: String) -> chip.Registry(Message, Groups) {
  case chip.from("sessions") {
    Ok(registry) -> registry
    Error(Nil) -> panic as "session is not available"
  }
}

Even with the wrapper above, there’s no guarantee of retrieving the right subject as a typo on the name might return a registry with different message types and groups.

members

</> 
pub fn members(
  registry: Subject(Message(a, b)),
  group: b,
  timeout: Int,
) -> List(Subject(a))

Retrieves all subjects from a given group. The order of retrieved subjects is not guaranteed.

Example

let assert Ok(registry) = chip.start(chip.Unnamed)

chip.register(registry, GroupA, subject)
chip.register(registry, GroupB, subject)
chip.register(registry, GroupA, subject)

let assert [_, _] = chip.members(registry, GroupA, 50)
let assert [_] = chip.members(registry, GroupB, 50)

register

</> 
pub fn register(
  registry: Subject(Message(a, b)),
  group: b,
  subject: Subject(a),
) -> Nil

Registers a subject under a group.

Example

let assert Ok(registry) = chip.start(chip.Unnamed)

chip.register(registry, GroupA, subject)
chip.register(registry, GroupB, subject)
chip.register(registry, GroupC, subject)

A subject may be registered under multiple groups but it may only be registered one time on each group.

It is possibel to register any subject at any point in time but keeping it under the initialization step of your process may help to keep things organized and tidy.

start

</> 
pub fn start(
  named: Named,
) -> Result(Subject(Message(a, b)), StartError)

Starts the registry.

Example

Normally, the registry may be started in an unnamed fashion. ///

> let assert Ok(registry) = chip.start(chip.Unnamed)

You will need to provide a mechanism to carry around the registry’s subject through your system.

It is also possible to start a named registry.

> let _ = chip.start(chip.Named("sessions"))

You may retrieve now this registry's by using the `from` function.

stop

</> 
pub fn stop(registry: Subject(Message(a, b))) -> Nil

Stops the registry.

Example

let assert Ok(registry) = chip.start(chip.Unnamed)
chip.stop(registry)
✨ Search Document