bath

Types

Msg

opaque </>

A message sent to the pool actor.

pub opaque type Msg(resource_type, resource_create_error)

Pool

opaque </>

The interface for interacting with a pool of resources in Bath.

pub opaque type Pool(resource_type, resource_create_error)

PoolConfig

opaque </>

Configuration for a Pool.

pub opaque type PoolConfig(resource_type, resource_create_error)

ShutdownError

</>

An error returned when the resource pool fails to shut down.

pub type ShutdownError {
  ResourcesInUse
  ShutdownTimeout
  CalleeDown(reason: dynamic.Dynamic)
}

Constructors

```
ResourcesInUse
```
There are still resources checked out. Ignore this failure case by calling shutdown function with force set to True.
```
ShutdownTimeout
```
The shutdown timeout expired.
```
CalleeDown(reason: dynamic.Dynamic)
```
The pool was already down or failed to send the response message.

StartError

</>

An error returned when creating a Pool.

pub type StartError(resource_create_error) {
  PoolStartResourceCreateError(resource_create_error)
  ActorStartError(actor.StartError)
}

Constructors

PoolStartResourceCreateError(resource_create_error)

```
ActorStartError(actor.StartError)
```

State

opaque </>

Pool actor state.

pub opaque type State(resource_type, resource_create_error)

Functions

apply

</>

pub fn apply(
  pool pool: Pool(a, b),
  timeout timeout: Int,
  next next: fn(a) -> c,
) -> Result(c, ApplyError(b))

Check out a resource from the pool, apply the next function, then check the resource back in.

let assert Ok(pool) =
  bath.new(fn() { Ok("Some pooled resource") })
  |> bath.start(1000)

use resource <- bath.apply(pool, 1000)
// Do stuff with resource...

child_spec

</>

pub fn child_spec(
  config pool_config: PoolConfig(a, b),
  timeout init_timeout: Int,
) -> Result(Spec(State(a, b), Msg(a, b)), StartError(b))

Create a child actor spec pool actor, for use in your application’s supervision tree, using the given PoolConfig. Once the pool is started, use from_subject to create a Pool from the Subject(bath.Msg(a, b)).

from_subject

</>

pub fn from_subject(
  subject subject: Subject(Msg(a, b)),
) -> Pool(a, b)

Create a Pool from a Subject(bath.Msg(a, b)). Useful when creating a pool as part of a supervision tree via the child_spec function.

new

</>

pub fn new(
  resource create_resource: fn() -> Result(a, b),
) -> PoolConfig(a, b)

Create a new PoolConfig for creating a pool of resources.

import bath
import fake_db

pub fn main() {
  // Create a pool of 10 connections to some fictional database.
  let assert Ok(pool) =
    bath.new(fn() { fake_db.connect() })
    |> bath.with_size(10)
    |> bath.start(1000)
}

Default values

Config	Default
`size`	10
`shutdown_resource`	`fn(_resource) { Nil }`
`checkout_strategy`	`FIFO`
`creation_strategy`	`Lazy`

shutdown

</>

pub fn shutdown(
  pool pool: Pool(a, b),
  force force: Bool,
  timeout timeout: Int,
) -> Result(Nil, ShutdownError)

Shut down the pool, calling the shutdown_function on each resource in the pool. Calling with force set to True will force the shutdown, not calling the shutdown_function on any resources.

Will fail if there are still resources checked out, unless force is True.

start

</>

pub fn start(
  config pool_config: PoolConfig(a, b),
  timeout init_timeout: Int,
) -> Result(Pool(a, b), StartError(b))

Start a pool actor using the given PoolConfig and return a Pool.

with_checkout_strategy

</>

pub fn with_checkout_strategy(
  config pool_config: PoolConfig(a, b),
  strategy checkout_strategy: CheckoutStrategy,
) -> PoolConfig(a, b)

Change the checkout strategy for the pool. Defaults to FIFO.

with_creation_strategy

</>

pub fn with_creation_strategy(
  config pool_config: PoolConfig(a, b),
  strategy creation_strategy: CreationStrategy,
) -> PoolConfig(a, b)

Change the resource creation strategy for the pool. Defaults to Lazy.

with_shutdown

</>

pub fn with_shutdown(
  config pool_config: PoolConfig(a, b),
  shutdown shutdown_resource: fn(a) -> Nil,
) -> PoolConfig(a, b)

Set a shutdown function to be run for each resource when the pool exits.

with_size

</>

pub fn with_size(
  config pool_config: PoolConfig(a, b),
  size size: Int,
) -> PoolConfig(a, b)

Set the pool size. Defaults to 10.