Reference

API

Every public type, method and value of the package. A signature is what the compiler reports, and the note under it is the one written beside the code.

1 package · 34 public items

moonpool

moonbitstack/moonpool

A pool of resources with no I/O of its own: it says which resource to hand out, whether to make another, which to let go, and when to refuse, and leaves the acting to the caller.

Values

letbackoff

pub let backoff : @moonward.Backoff

letforever

A span meaning "no limit", which is what zero is taken to mean for the two ages: a resource with no maximum age is never too old.

pub let forever : @moondate.Span

letlimits

The preset: ten live at once, ten of them allowed to sit idle, discarded after thirty minutes idle and never by age. Ten live is what most services settle on, and thirty minutes is long enough that a warm pool survives a quiet spell. Keeping idle equal to size means a pool that grew under load does not immediately throw away what it just made.

pub let limits : Limits

letward

pub let ward : Ward

Types

structLimits

The limits a pool holds itself to. The preset is limits. Build another with Limits::new, or update one in place with { ..limits, size: 32 }.

pub(all) struct Limits {

size : Int32
idle : Int32
keep : @moondate.Span
life : @moondate.Span

fnLimits::new

Limits by name, every knob with the preset's value.

pub fn Limits::new(size? : Int32, idle? : Int32, keep? : @moondate.Span, life? : @moondate.Span) -> Self

opaquePool

The bookkeeping of holding a limited number of things. It does not open, close, or wait — a caller with a runtime does all three. What it knows is how many are live, which are idle, which are lent and since when each was made, and which have sat or lived long enough to be let go. Time is passed in as whatever the caller's clock reads, in nanoseconds; the value's origin does not matter because only differences are used. That is what makes a test drive a pool through an hour in three lines. A lent resource is recognised on its way back by identity, which is what every connection handle has. That is how its birth survives the loan: a pool that stamped a returned resource as new would never retire one by age, however old. Idle resources are kept as (item, born, rested), lent ones as (item, born, ticket), and each resource being made as the breaker's promise and the shedder's ticket it will settle.

type Pool[T]

fnPool::busy

pub fn[T] Pool::busy(Self[T]) -> Int32

fnPool::close

pub fn[T] Pool::close(Self[T]) -> Array[T]

fnPool::drop

pub fn[T] Pool::drop(Self[T], T) -> Unit

fnPool::evict

pub fn[T] Pool::evict(Self[T], Int64) -> Array[T]

fnPool::give

pub fn[T] Pool::give(Self[T], T, Int64) -> Bool

fnPool::idle

pub fn[T] Pool::idle(Self[T]) -> Int32

fnPool::live

pub fn[T] Pool::live(Self[T]) -> Int32

fnPool::made

pub fn[T] Pool::made(Self[T], T, Int64) -> Unit

fnPool::new

pub fn[T] Pool::new(limits? : Limits, ward? : Ward) -> Self[T]

fnPool::refusal

pub fn[T] Pool::refusal(Self[T], Int64) -> Double

fnPool::take

pub fn[T] Pool::take(Self[T], Int64, roll? : Double, cpu? : Int32) -> Taken[T]

fnPool::unmade

pub fn[T] Pool::unmade(Self[T], Int64, roll? : Double) -> Unit

structRoundRobin

Takes turns. It holds only a cursor, so it costs nothing to keep one per client.

pub struct RoundRobin {

// private fields

fnRoundRobin::new

A rotation starting at the first target.

pub fn RoundRobin::new() -> Self

fnRoundRobin::pick

The next of count targets, or -1 when there are none. The cursor wraps at the current count, so it stays valid as targets come and go.

pub fn RoundRobin::pick(Self, Int32) -> Int32

enumTaken

What a pool answers when asked for a resource. It never blocks and never opens anything: waiting and connecting both need a runtime, and this package has none. Make is the pool saying there is room for another, and reserving it; Wait is it saying there is not, and the caller's queue decides what that means. Stale is an idle resource too old to use, handed back so the caller can close it before asking again. The last two come only from a Ward: Later is making held back for that long, by the bucket or by backoff after a failure; Shed is the breaker refusing new connections to a failing backend, or the shedder refusing to lend while the process is overloaded.

pub(all) enum Taken[T] {

Ready(T)
Stale(T)
Make
Wait
Later(@moondate.Span)
Shed

structWard

What stands in front of a pool's backend. Every part is optional and the preset has none, which leaves the pool exactly as it is without a ward.

pub(all) struct Ward {

breaker : @moonward.Breaker?
bucket : @moonward.Bucket?
backoff : @moonward.Backoff?
shedder : @moonward.Shedder?

fnWard::new

pub fn Ward::new(breaker? : @moonward.Breaker, bucket? : @moonward.Bucket, backoff? : @moonward.Backoff, shedder? : @moonward.Shedder) -> Self

structWeighted

Smooth weighted round-robin, nginx's: every pick credits each target with its weight, serves the one with the most credit, and charges it the total. Over a cycle each target gets its share, and the turns interleave: a weight of 5 is not five requests back to back. Credit is kept by name, so the list can change order between picks. A target that leaves loses its credit, which was earned under weights that may no longer hold.

pub struct Weighted {

// private fields

fnWeighted::new

A balancer with no credit yet.

pub fn Weighted::new() -> Self

fnWeighted::pick

The index of the next of targets, each a name and a weight. A weight of zero or less is never picked, and -1 means nothing can be.

pub fn Weighted::pick(Self, ArrayView[(String, Int32)]) -> Int32

Functions