constellation/source

Demand grants used by asynchronous sources.

A grant reserves downstream capacity. Sources may supply it in parts and may retain it while temporarily empty, without polling the Stage.

Types

DemandGrant

opaque </>

Capacity reserved for one asynchronous source request.

pub opaque type DemandGrant

Event

</>

Notifications emitted to an attached asynchronous source.

pub type Event {
  DemandGranted(DemandGrant)
  GrantRevoked(DemandGrant)
  SourceStopped
}

Constructors

```
DemandGranted(DemandGrant)
```
```
GrantRevoked(DemandGrant)
```
```
SourceStopped
```

Source

opaque </>

A typed capability used to supply events for demand grants.

pub opaque type Source(event)

SourceError

</>

Errors returned by a source attached to an OTP worker pool.

pub type SourceError {
  SupplyProtocol(SupplyError)
  SourceMismatch
  SourceTimeout
  SourceUnavailable
}

Constructors

```
SupplyProtocol(SupplyError)
```
```
SourceMismatch
```
```
SourceTimeout
```
```
SourceUnavailable
```

SupplyError

</>

Protocol errors returned while supplying a demand grant.

pub type SupplyError {
  OffsetGap(expected: Int, provided: Int)
  OffsetOverlap(accepted_until: Int, provided_until: Int)
  GrantExceeded(remaining: Int, provided: Int)
}

Constructors

```
OffsetGap(expected: Int, provided: Int)
```

OffsetOverlap(accepted_until: Int, provided_until: Int)

GrantExceeded(remaining: Int, provided: Int)

SupplyResult

</>

Result of supplying part of a demand grant.

pub type SupplyResult {
  Accepted(next_offset: Int, remaining: Int)
  Duplicate
  StaleGrant
}

Constructors

Accepted(next_offset: Int, remaining: Int)

```
Duplicate
```
```
StaleGrant
```

Values

available

</>

pub fn available(source: Source(event)) -> Nil

Resumes grant notifications for current downstream capacity.

grant_amount

</>

pub fn grant_amount(grant: DemandGrant) -> Int

Returns the maximum number of events reserved by a grant.

supply

</>

pub fn supply(
  source: Source(event),
  grant: DemandGrant,
  offset: Int,
  events: List(event),
) -> Result(SupplyResult, SourceError)

Supplies the next contiguous portion of a demand grant.

Retrying an already accepted range is safe and returns Duplicate while its grant remains in the source’s bounded recent-completion window.

unavailable

</>

pub fn unavailable(source: Source(event)) -> Nil

Suspends grants and revokes all capacity currently reserved by this source.