ecluse:ecluse-core
Safe HaskellNone
LanguageGHC2021

Ecluse.Core.Server.Admission.Meter

Description

The metadata memory budget and ticket accounting. Entry waits use the deadline sweeper. Started work pays in steps and shares one overdraw token with the work it awaits. Finished phases return their charge before the ticket closes.

Synopsis

The meter

data MemoryMeter Source #

The process-wide meter. The constructor stays hidden so only the checked operations change it.

data MeterSettings Source #

The boot-time shape of a meter.

Constructors

MeterSettings 

Fields

newMemoryMeter :: Deadlines -> MeterSettings -> IO MemoryMeter Source #

Build a meter. The step floors at one byte, and the room and the wait at zero. A positive wait ends on a sweep of the deadlines, so a fixture that never waits one out may leave them unswept.

meterLine :: MemoryMeter -> Line Source #

The line of requests this gate turned away at a full room.

steerMeter :: MemoryMeter -> Int -> BrakeLevel -> IO () Source #

Move the budget and record the brake level that moved it. Paused reads and queued entries retry at once.

meterSnapshot :: MemoryMeter -> IO MeterSnapshot Source #

Read the meter's figures without blocking a request.

meterFigures :: MemoryMeter -> STM MeterSnapshot Source #

The meter's figures inside a transaction, so a caller can wait for them to change.

takeLargestCharge :: MemoryMeter -> IO Int Source #

The largest total one ticket reached since the last call, for the sampler alone.

A request's ticket

data MemoryTicket Source #

One request's account with the meter, or a view of it that pays for shared work.

withMemoryEntry :: MonadUnliftIO m => MetricsPort -> MemoryMeter -> (MemoryTicket -> m a) -> m (Either Shed a) Source #

Run a request under the meter, or say why it was shed: the waiting room was full, or the entry step did not fit within the wait. Everything the ticket paid returns on every exit path.

tryMemoryEntry :: MonadUnliftIO m => MetricsPort -> MemoryMeter -> (MemoryTicket -> m a) -> m (Either Shed a) Source #

Try memory entry without recording a final refusal, so callers can retry admission.

charge :: MemoryTicket -> Int -> IO () Source #

Pay for bytes the request is about to hold, already scaled to their charge.

newChargeRegion :: (Int -> IO ()) -> IO (Int -> IO ()) Source #

Pay only increases within one sequential workspace. Overlapping work requires separate regions.

newChargePair :: (Int -> IO ()) -> IO (Int -> IO (), Int -> IO ()) Source #

Two portions of one workspace, each set absolutely. Every change pays their saturated sum.

Giving charge back

data ChargePart Source #

What one phase of a request paid onto its ticket, so the phase can give it back once the data it paid for is dead.

newChargePart :: MemoryTicket -> IO ChargePart Source #

A part of the ticket that has paid nothing yet.

chargePart :: ChargePart -> Int -> IO () Source #

Pay through the part, so the part may give the cost back later.

servingPart :: FlightKey -> ChargePart -> ChargePart Source #

The same part, paying for shared work as servingFlight does.

stepDown :: ChargePart -> Int -> IO () Source #

Give back what the part paid above kept bytes, in one transaction with the meter. A part gives back only its own payments and each of them once, and nothing after its ticket is released.

Shared work

awaitingFlight :: MonadUnliftIO m => MemoryTicket -> FlightKey -> m a -> m a Source #

Mark this request as waiting on a unit of shared work for the length of the action, so the request that does that work may pause and overdraw with this request's priority.

servingFlight :: FlightKey -> MemoryTicket -> MemoryTicket Source #

The same ticket, paying for shared work: its charges carry the priority of every request waiting on it.