Struct OrderIdMap 

pub struct OrderIdMap { /* private fields */ }

Bidirectional mapping between rustrade ClientOrderId and IB order IDs.

IB uses i32 order IDs from a sequence. Barter uses ClientOrderId (SmolStr). This map maintains the bidirectional relationship and stores order context for reconstructing full Order structs from OrderStatus callbacks.

A client order id names one live order at a time

TWS receives a ClientOrderId only as the order’s reference (order_ref), whose uniqueness it does not check, so this map is the only place it can be kept. An id is held from register until its order ends, and registering an id already held is refused with ClientOrderIdInUse. Once its order has ended the id may name a new order.

An order ends here when the account stream reports it Filled, Cancelled or Inactive, or when clear_stale reaps it. A Filled order releases its id (release_client_id) but keeps its IB-id entry, so the executions and commissions IB may still send for it resolve to the id it was placed under. That entry is reaped by clear_stale.

Every removal is conditional on the id still naming the order removed, so an earlier order under a reused id cannot take the mapping of the order now under it. Its late executions and commissions still resolve to the id, carrying its own IB order ID, while a status IB re-sends for it is dropped by the account stream (names_other_order).

Implementations

impl OrderIdMap

pub fn new() -> Self

pub fn register( &self, client_id: ClientOrderId, ib_id: i32, context: OrderContext, ) -> Result<(), ClientOrderIdInUse>

Register a mapping between ClientOrderId and IB order ID with order context.

Errors

ClientOrderIdInUse if a live order already holds client_id. Nothing is registered.

pub fn register_all<const N: usize>( &self, orders: [(ClientOrderId, i32, OrderContext); N], ) -> Result<(), ClientOrderIdInUse>

Register several orders at once, such as the legs of a bracket: all of them or none.

Errors

ClientOrderIdInUse, naming the first id at fault, if a live order already holds one of the ids or two of orders share one. Nothing is registered.

pub fn get_ib_id(&self, client_id: &ClientOrderId) -> Option<i32>

Look up the IB order ID of the live order under client_id.

pub fn contains(&self, ib_id: i32) -> bool

Whether IB order ib_id has an entry: a live order, or a filled one not yet reaped.

pub fn get_client_id(&self, ib_id: i32) -> Option<ClientOrderId>

Look up ClientOrderId by IB order ID.

pub fn get_client_id_and_context( &self, ib_id: i32, ) -> Option<(ClientOrderId, OrderContext)>

Look up ClientOrderId and OrderContext together by IB order ID (single lookup).

pub fn names_other_order(&self, client_id: &ClientOrderId, ib_id: i32) -> bool

Whether client_id now names a live order other than ib_id: the id was freed when ib_id ended and has since been registered again.

pub fn release_client_id( &self, ib_id: i32, ) -> Option<(ClientOrderId, OrderContext)>

Free the id of the filled order ib_id, keeping its entry, and return both, in a single write lock acquisition.

Use this for a Filled status: the id may then name a new order, while the executions and commissions IB may still send for this one resolve to it by IB id.

pub fn remove_and_get_context( &self, ib_id: i32, ) -> Option<(ClientOrderId, OrderContext)>

Remove mapping and return context in a single write lock acquisition.

Use this for terminal status events (Cancelled/Inactive) to avoid the read-then-write pattern of get_client_id_and_context + remove_by_ib_id. The id’s mapping is removed only if it still names ib_id.

pub fn remove_by_ib_id(&self, ib_id: i32) -> Option<ClientOrderId>

Remove a mapping by IB order ID (used when an order failed or was rolled back).

The id’s mapping is removed only if it still names ib_id.

pub fn clear_stale(&self, max_age: Duration) -> usize

Clear order ID mappings older than the given duration.

Returns the number of cleared entries.

Why This Is Needed

IB does not guarantee event ordering between OrderStatus("Filled") and ExecutionData/CommissionReport. For fast-filling orders (especially market orders), execution data may arrive AFTER the filled status — or the filled status may not arrive at all. So a Filled status frees the order’s client id but keeps its IB-id entry, and an order whose terminal status never arrives keeps both.

Call this method periodically to clean up old mappings. A reasonable interval is 5-10 minutes with a max_age of 1 hour. An order still working past max_age is cleared too, freeing its id.

pub fn len(&self) -> usize

Number of live orders: those holding a client id.

pub fn is_empty(&self) -> bool

Check if no order is live.

Trait Implementations

impl Clone for OrderIdMap

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for OrderIdMap

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for OrderIdMap

fn default() -> Self

Returns the “default value” for a type.