GitHub

Price Levels

StockMarketABM.PriceLevelMod implements the FIFO queue that stores all resting orders at a single price. A price level owns:

  • queue: a Vector{Union{T,Nothing}} that holds orders in arrival order; cancelled entries are set to nothing instead of being removed immediately.
  • head: an index pointing to the next live entry. _advance_head! skips cancelled slots so first and peek_head always see the active head.
  • idxmap: a Dict{OrderId,Int32} mapping order identifiers to their position in queue, which allows O(1) cancellations.
  • active and total_qty: cached counts so isempty, length, and level_qty are constant time.

The main operations are structured around this layout:

  1. push! appends the new order to the vector, records its index in idxmap and updates the caches. Appending is amortised O(1).
  2. cancel! looks up the index in idxmap, replaces the slot with nothing, adjusts the cached counters, and advances the head if the cancelled order was at the front.
  3. consume_head! calls _advance_head!, retrieves the live head order, and either removes it entirely (when filled) or rewrites the slot with the same order but with the outstanding quantity produced by _with_qty.
  4. _maybe_trim! periodically compacts the buffer by shifting live entries to

the front when enough leading cancellations accumulate, keeping memory usage bounded.

  1. All operations assume incoming orders carry unique OrderId values; the level trusts callers to enforce this and does not perform additional checks.

Because the queue is per price level, scanning levels in price order is handled by the order book while the level itself focuses on fast per-price mutations.

StockMarketABM.PriceLevelMod.PriceLevel — Type
PriceLevel{T}(price)

FIFO queue for a single price level with O(1) push/popfirst/cancel by id. Assumes T has field id::OrderId. Also assumes T has field qty::Qty for running quantity totals. Vacated slots are compacted lazily: cancellations leave nothing markers that get reclaimed when the head advances far enough to trigger internal trimming.

source
Base.first — Method
first(pl::PriceLevel)

Return the raw queue entry at the head without enforcing the element type. This helper is internal; prefer peek_head for a typed view of the resting order.

source
Base.push! — Method
push!(pl, order)

Append order to the price level, updating the index map and cached quantity. The order must expose id::OrderId and qty::Qty fields. Callers are responsible for ensuring ord.id is unique; duplicates are not guarded against at this layer.

source
StockMarketABM.PriceLevelMod.cancel! — Method
cancel!(pl, id::OrderId) -> Bool

Remove the order with identifier id from the level in O(1) time. Returns true when the order existed, otherwise false. The cleared slot is set to nothing and will be skipped until the structure compacts old holes.

source
StockMarketABM.PriceLevelMod.consume_head! — Method
consume_head!(pl, qty) -> Union{Nothing,Tuple{T,Qty,Qty}}

Fill up to qty against the resting order at the head of the level. When a match occurs the returned tuple contains (order, filled, remaining) where order is the pre-fill order instance, filled is the executed quantity and remaining is what stays on the book. Returns nothing if the level is empty or no quantity needs to be consumed.

source
StockMarketABM.PriceLevelMod.peek_head — Method
peek_head(pl) -> Union{T,Nothing}

Return the active order at the front of the price level while preserving the element type T. Returns nothing when the level has no resting orders.

source