pub struct PositionRefMut<'a>(/* private fields */);Expand description
Lifetime-scoped exclusive write borrow of a cached position.
Returned by crate::cache::Cache::position_mut. While the borrow is alive, no other read or
write on the same cell is permitted (enforced at runtime by the underlying RefMut).
Drop the borrow before dispatching events or taking any other cache borrow that may re-enter
the same position.
Implementations§
Methods from Deref<Target = Position>§
pub fn clone_without_events(&self) -> Position
pub fn clone_without_events(&self) -> Position
Returns a copy without stored events, adjustments, replay events, fill voids, or trade IDs.
§Warning
Use this copy only as transient read state. Applying events or caching this copy can bypass replay and duplicate-fill checks and discard position history.
pub fn clone_for_snapshot(&self) -> Position
pub fn clone_for_snapshot(&self) -> Position
Returns a snapshot copy without durable replay or fill-void history.
pub fn transfer_replay_state_from(&mut self, prior: &mut Position)
pub fn transfer_replay_state_from(&mut self, prior: &mut Position)
Moves durable replay state from prior and keeps this position’s current replay events.
pub fn purge_events_for_order(&mut self, client_order_id: ClientOrderId)
pub fn purge_events_for_order(&mut self, client_order_id: ClientOrderId)
Purges all order fill events for the given client order ID and recalculates derived state.
§Warning
This operation recalculates the entire position from scratch after removing the specified order’s fills. This is an expensive operation and should be used sparingly.
§Panics
Panics if after purging, no fills remain and the position cannot be reconstructed.
pub fn apply(&mut self, fill: &OrderFilled)
pub fn apply(&mut self, fill: &OrderFilled)
Applies an OrderFilled event to this position.
A fill with the same trade_id, the same client_order_id, and a new price restates
the open average when that trade is an opening fill in the current cycle. Quantity is
unchanged. The original fill stays in events, so a void still matches its last_px.
Applying the same event_id again does nothing. A different order that reuses the trade
ID is rejected. A closing fill does not change the open average, and restating an
opening fill does not change realized PnL for quantity already closed.
§Panics
Panics if fill.trade_id is already in trade_ids and this fill is not a restatement
of that order.
pub fn try_apply(&mut self, fill: &OrderFilled) -> Result<(), CorrectnessError>
pub fn try_apply(&mut self, fill: &OrderFilled) -> Result<(), CorrectnessError>
Applies an OrderFilled event to this position with correctness checking.
A fill with the same trade_id, the same client_order_id, and a new price restates
the open average when that trade is an opening fill in the current cycle. Quantity is
unchanged. An error leaves the position unchanged. Applying the same event_id again
does nothing. A closing fill does not change the open average.
§Errors
Returns an error if:
- The fill instrument or position identity does not match this position.
- The fill has no position ID.
- The precision of the fill price, quantity, or a commission converted through
f64exceedsMAX_FLOAT_PRECISION. fill.trade_idis already intrade_idsand this fill is not a restatement of that order.
pub fn has_replay_trade_id(&self, trade_id: TradeId) -> bool
pub fn has_replay_trade_id(&self, trade_id: TradeId) -> bool
Returns whether durable replay history contains trade_id.
pub fn apply_adjustment(&mut self, adjustment: PositionAdjusted)
pub fn apply_adjustment(&mut self, adjustment: PositionAdjusted)
Applies a position adjustment event.
This method handles adjustments to position quantity or realized PnL that occur outside of normal order fills, such as:
- Commission adjustments in base currency (crypto spot markets).
- Funding payments (perpetual futures).
The adjustment event is stored in the position’s adjustment history for full audit trail.
§Panics
Panics if the adjustment’s quantity_change cannot be converted to f64.
pub fn revert_last_adjustment(
&mut self,
prior: &Position,
) -> Result<(), CorrectnessError>
pub fn revert_last_adjustment( &mut self, prior: &Position, ) -> Result<(), CorrectnessError>
Reverts the most recent adjustment applied with [Self::apply_adjustment].
prior is a snapshot of this position taken before that adjustment was applied, for
example with [Self::clone_without_events]; the state an adjustment changes is restored
from it, and the adjustment is removed from the position history.
An adjustment can leave every field the snapshot is checked on unchanged, for example a zero value funding payment, so the snapshot must also not be older than the latest adjustment that stays in the history. This assumes adjustments are applied in timestamp order, as the backtest does; a stale snapshot behind out of order adjustments can pass.
§Errors
Returns an error if prior is a snapshot of a different position, size precision or
settlement currency, the last replay event is not the latest adjustment (for example a
fill was applied after it), prior predates the adjustment before the latest one, its
realized PnL cannot take the adjustment’s PnL change (another currency, or out of
Money bounds), or applying that adjustment to prior does not reproduce the current
state. An error leaves the position unchanged.
pub fn apply_instrument_close(
&mut self,
close: InstrumentClose,
) -> Result<(), Error>
pub fn apply_instrument_close( &mut self, close: InstrumentClose, ) -> Result<(), Error>
Settles the open position at the payout price of an authoritative contract expiration.
The settlement closes the current cycle at close.close_price and books its realized PnL
without an order fill. Fill quantities and commissions stay as filled. The close is
recorded in the replay history, so [Self::is_settled] holds until a later fill reopens
the position.
§Errors
Returns an error if the close targets another instrument, is not a contract expiration, the position is not open, or the settlement PnL cannot be represented. An error leaves the position unchanged.
pub fn apply_fill_void(
&mut self,
event: OrderFillVoided,
voided_qty: Quantity,
commission_voided: Option<Money>,
) -> Result<Option<Money>, Error>
pub fn apply_fill_void( &mut self, event: OrderFillVoided, voided_qty: Quantity, commission_voided: Option<Money>, ) -> Result<Option<Money>, Error>
Applies a cumulative fill correction allocated to this position and rebuilds derived state.
Returns the realized PnL of the cycles the rebuild closed before the current one, which
[Self::realized_pnl] no longer holds because reopening from flat resets it. A caller
archiving closed cycles needs this to keep their PnL once the correction has moved the
cycle boundaries its existing archive describes. None when the corrected history never
goes flat, so the current cycle covers all of it.
§Errors
Returns an error if the allocation is stale, duplicated, exceeds known fragments, or has a commission currency that differs from those fragments.
pub fn fill_fragments(
&self,
client_order_id: ClientOrderId,
trade_id: TradeId,
) -> Vec<&OrderFilled>
pub fn fill_fragments( &self, client_order_id: ClientOrderId, trade_id: TradeId, ) -> Vec<&OrderFilled>
Returns durable fill fragments matching an order trade in local application order.
pub fn try_calculate_pnl(
&self,
avg_px_open: f64,
avg_px_close: f64,
quantity: Quantity,
) -> Result<Money, Error>
pub fn try_calculate_pnl( &self, avg_px_open: f64, avg_px_close: f64, quantity: Quantity, ) -> Result<Money, Error>
Calculates profit and loss from the given prices and quantity.
§Errors
Returns an error if the quantity precision exceeds
MAX_FLOAT_PRECISION, inverse P&L cannot be
calculated, or the result cannot be represented as [Money].
pub fn calculate_pnl(
&self,
avg_px_open: f64,
avg_px_close: f64,
quantity: Quantity,
) -> Money
pub fn calculate_pnl( &self, avg_px_open: f64, avg_px_close: f64, quantity: Quantity, ) -> Money
Calculates profit and loss from the given prices and quantity.
pub fn try_total_pnl(&self, last: Price) -> Result<Money, Error>
pub fn try_total_pnl(&self, last: Price) -> Result<Money, Error>
Returns total P&L (realized + unrealized) based on the last price.
§Errors
Returns an error if unrealized P&L cannot be calculated, the realized and unrealized
currencies differ, or the total cannot be represented as [Money].
pub fn total_pnl(&self, last: Price) -> Money
pub fn total_pnl(&self, last: Price) -> Money
Returns total P&L (realized + unrealized) based on the last price.
pub fn try_unrealized_pnl(&self, last: Price) -> Result<Money, Error>
pub fn try_unrealized_pnl(&self, last: Price) -> Result<Money, Error>
Returns unrealized P&L based on the last price.
§Errors
Returns an error if the position is not flat and the last precision exceeds
MAX_FLOAT_PRECISION, inverse P&L cannot be
calculated, or the result cannot be represented as [Money].
pub fn unrealized_pnl(&self, last: Price) -> Money
pub fn unrealized_pnl(&self, last: Price) -> Money
Returns unrealized P&L based on the last price.
pub fn closing_order_side(&self) -> Option<OrderSide>
pub fn closing_order_side(&self) -> Option<OrderSide>
Returns the order side required to close this position.
pub fn is_opposite_side(&self, side: OrderSide) -> bool
pub fn is_opposite_side(&self, side: OrderSide) -> bool
Returns whether the given order side is opposite to the position entry side.
pub fn symbol(&self) -> Symbol
pub fn symbol(&self) -> Symbol
Returns the instrument symbol.
pub fn venue(&self) -> Venue
pub fn venue(&self) -> Venue
Returns the trading venue.
pub fn event_count(&self) -> usize
pub fn event_count(&self) -> usize
Returns the count of order fill events applied to this position.
pub fn client_order_ids(&self) -> Vec<ClientOrderId>
pub fn client_order_ids(&self) -> Vec<ClientOrderId>
Returns unique client order IDs from all fill events, sorted.
pub fn venue_order_ids(&self) -> Vec<VenueOrderId>
pub fn venue_order_ids(&self) -> Vec<VenueOrderId>
Returns unique venue order IDs from all fill events, sorted.
pub fn try_notional_value(&self, last: Price) -> Result<Money, Error>
pub fn try_notional_value(&self, last: Price) -> Result<Money, Error>
Calculates the notional value based on the last price.
§Errors
Returns an error if this is an inverse position without a base currency, the price is not
positive for a non-premium inverse position, or the result cannot be represented as
[Money].
pub fn notional_value(&self, last: Price) -> Money
pub fn notional_value(&self, last: Price) -> Money
Calculates the notional value based on the last price.
§Panics
Panics if [Position::try_notional_value] returns an error.
pub fn last_event(&self) -> Option<OrderFilled>
pub fn last_event(&self) -> Option<OrderFilled>
Returns the last OrderFilled event for the position (if any after purging).
pub fn last_trade_id(&self) -> Option<TradeId>
pub fn last_trade_id(&self) -> Option<TradeId>
Returns the last TradeId for the position (if any after purging).
pub fn is_open(&self) -> bool
pub fn is_open(&self) -> bool
Returns whether the position is currently open (has quantity and no close timestamp).
pub fn is_closed(&self) -> bool
pub fn is_closed(&self) -> bool
Returns whether the position is closed (flat with a close timestamp).
pub fn is_settled(&self) -> bool
pub fn is_settled(&self) -> bool
Returns whether an authoritative instrument close settled the current cycle.
Reads the replay history, so it is false for a copy made by
[Self::clone_without_events] or [Self::clone_for_snapshot].
pub fn requires_replay_state(&self) -> bool
pub fn requires_replay_state(&self) -> bool
Returns whether replaying the position’s fills alone cannot rebuild its state.
Fill voids, settlements, and price restatements change state without a new quantity-bearing fill, so persistence must store the complete replay state. Retained virtual position cycles also require the complete replay state.
pub fn signed_decimal_qty(&self) -> Decimal
pub fn signed_decimal_qty(&self) -> Decimal
Returns the signed quantity as a Decimal.
Uses the raw signed_qty field to preserve full precision, as the quantity
field may have reduced precision based on the instrument’s size_precision.
pub fn commissions(&self) -> Vec<Money>
pub fn commissions(&self) -> Vec<Money>
Returns the cumulative commissions for the position as a vector.