Class L3BookBuilder

java.lang.Object
com.quantfinlib.marketdata.L3BookBuilder
public final class L3BookBuilder extends Object
Participant-side full-depth (L3) book builder: reconstructs a venue's book from an ITCH-style event stream (add / execute / cancel / delete / replace) and answers the questions an execution engine actually asks — best bid/ask, depth, and exactly how many shares are queued ahead of my order — with zero allocation on every event.

Same engineering as orderbook.HftOrderBook (dense tick ladder, occupancy bitmaps, pooled intrusive nodes, open-addressing ref map with backward-shift deletion), but driven by the feed instead of by matching: this is the consumer of a venue's L3 feed, not the venue.

Queue position

Call track(long) with your own order's reference (learned from the order-entry gateway's ack) once its add has appeared on the feed. The initial shares-ahead is computed by one walk of the level's FIFO; from then on it is maintained in O(1) per event using two facts of price-time priority: executions always consume the queue head (so any execution at your level that isn't you happened ahead of you), and a cancel is ahead of you iff it entered the queue before you (insertion sequence numbers). When your order fills, is deleted, or is replaced, tracking ends automatically.

Threading: single-writer — one feed-handler thread owns the book. Order references must be positive (0 is the map's empty sentinel), which matches real ITCH feeds.

  • Constructor Summary

    Constructors
    Constructor
    Description
    L3BookBuilder(int stockLocate, int minPriceTick, int maxPriceTick, int maxOrders)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    addCount()
     
    long
    bestAskSize()
     
    int
    bestAskTick()
    Best ask in absolute 0.0001 ticks; Integer.MAX_VALUE when none.
    long
    bestBidSize()
     
    int
    bestBidTick()
    Best bid in absolute 0.0001 ticks; Integer.MIN_VALUE when none.
    long
    cancelCount()
     
    long
    deleteCount()
     
    long
    duplicateRefCount()
    Adds re-delivering a live ref, rejected to protect the book (replay symptom).
    long
    executeCount()
     
    int
    lastTradeTick()
     
    boolean
    onAdd(long ref, Side side, long shares, int priceTick)
    Add order: appends to its level's FIFO.
    void
    onCancel(long ref, long shares)
    Partial cancel: reduces a resting order in place (keeps its priority).
    void
    onDelete(long ref)
    Full removal of a resting order.
    void
    onExecute(long ref, long shares)
    Execution against a resting order (always the queue head under price-time priority — which is what makes O(1) queue tracking sound).
    int
    onMessage(byte[] buf, int offset)
    Applies one wire message starting at offset.
    void
    onReplace(long origRef, long newRef, long shares, int priceTick)
    Cancel/replace: the original order is removed and the new reference joins the back of the (possibly different) level's queue — priority is lost, exactly as on a real venue.
    void
    onTrade(int priceTick)
    Off-book/non-displayed trade print: records it, book unchanged.
    long
    openQuantity(long ref)
    Open shares of any resting order by ref; 0 when gone/unknown.
    long
    outOfBandCount()
    Orders dropped for off-band prices or an exhausted pool — adds AND replace re-adds (widen the band/pool; off-band liquidity is invisible to this book by design, and its later events count as unknown refs).
    long
    qtyAtTick(Side side, int priceTick)
    Resting quantity at an absolute tick (0 when off-band or empty).
    long
    replaceCount()
     
    int
    restingOrders()
     
    long
    sharesAhead(long ref)
    Shares queued ahead of a tracked order right now; -1 when the ref is not tracked (never was, or it filled / was deleted / was replaced).
    int
    snapshot(Side side, int[] outTicks, long[] outQtys)
    Depth snapshot into caller arrays, best-first; returns levels written.
    boolean
    track(long ref)
    Starts queue tracking for a resting order (yours, learned from your gateway ack).
    long
    tradeCount()
     
    long
    unknownRefCount()
    Events referencing unknown orders (feed gap symptom — resubscribe/snapshot).
    void
    untrack(long ref)
    Stops tracking a ref (no-op when not tracked).

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • L3BookBuilder

      public L3BookBuilder(int stockLocate, int minPriceTick, int maxPriceTick, int maxOrders)
      Parameters:
      stockLocate - the feed's locate code for the symbol this book tracks; messages for other locates are ignored by onMessage(byte[], int)
      minPriceTick - lowest representable price in 0.0001 ticks (inclusive)
      maxPriceTick - highest representable price in 0.0001 ticks (inclusive)
      maxOrders - resting-order capacity (pool size, fixed forever)

  • Method Details

    • onMessage

      public int onMessage(byte[] buf, int offset)
      Applies one wire message starting at offset. Returns the wire length consumed, or 0 when the message is for another stock locate or outside the supported subset (callers skip it by its own length).

    • onAdd

      public boolean onAdd(long ref, Side side, long shares, int priceTick)
      Add order: appends to its level's FIFO. False when the order was dropped (off-band price, exhausted pool, or a duplicate ref — a feed anomaly that would otherwise corrupt the ref map).

    • onExecute

      public void onExecute(long ref, long shares)
      Execution against a resting order (always the queue head under price-time priority — which is what makes O(1) queue tracking sound).

    • onCancel

      public void onCancel(long ref, long shares)
      Partial cancel: reduces a resting order in place (keeps its priority).

    • onDelete

      public void onDelete(long ref)
      Full removal of a resting order.

    • onReplace

      public void onReplace(long origRef, long newRef, long shares, int priceTick)
      Cancel/replace: the original order is removed and the new reference joins the back of the (possibly different) level's queue — priority is lost, exactly as on a real venue. A replace re-pricing to an off-band level drops the order entirely, consistent with off-band adds: prices outside the configured band are invisible to this book by design.

    • onTrade

      public void onTrade(int priceTick)
      Off-book/non-displayed trade print: records it, book unchanged.

    • track

      public boolean track(long ref)
      Starts queue tracking for a resting order (yours, learned from your gateway ack). The initial shares-ahead is one FIFO walk; maintenance is O(1) per event afterwards. Returns false when the ref is unknown or the tracking table (64 orders) is full.

    • untrack

      public void untrack(long ref)
      Stops tracking a ref (no-op when not tracked).

    • sharesAhead

      public long sharesAhead(long ref)
      Shares queued ahead of a tracked order right now; -1 when the ref is not tracked (never was, or it filled / was deleted / was replaced). This is the exact position from the L3 feed; when only L2 (aggregated level sizes) is available, use the probabilistic microstructure.QueuePositionEstimator instead.

    • bestBidTick

      public int bestBidTick()
      Best bid in absolute 0.0001 ticks; Integer.MIN_VALUE when none.

    • bestAskTick

      public int bestAskTick()
      Best ask in absolute 0.0001 ticks; Integer.MAX_VALUE when none.

    • bestBidSize

      public long bestBidSize()

    • bestAskSize

      public long bestAskSize()

    • qtyAtTick

      public long qtyAtTick(Side side, int priceTick)
      Resting quantity at an absolute tick (0 when off-band or empty).

    • openQuantity

      public long openQuantity(long ref)
      Open shares of any resting order by ref; 0 when gone/unknown.

    • snapshot

      public int snapshot(Side side, int[] outTicks, long[] outQtys)
      Depth snapshot into caller arrays, best-first; returns levels written.

    • lastTradeTick

      public int lastTradeTick()

    • restingOrders

      public int restingOrders()

    • addCount

      public long addCount()

    • executeCount

      public long executeCount()

    • cancelCount

      public long cancelCount()

    • deleteCount

      public long deleteCount()

    • replaceCount

      public long replaceCount()

    • tradeCount

      public long tradeCount()

    • unknownRefCount

      public long unknownRefCount()
      Events referencing unknown orders (feed gap symptom — resubscribe/snapshot).

    • outOfBandCount

      public long outOfBandCount()
      Orders dropped for off-band prices or an exhausted pool — adds AND replace re-adds (widen the band/pool; off-band liquidity is invisible to this book by design, and its later events count as unknown refs).

    • duplicateRefCount

      public long duplicateRefCount()
      Adds re-delivering a live ref, rejected to protect the book (replay symptom).