engine.md

Engine

Back to index

OpenPitSyncPolicy

Runtime selector for the engine's storage synchronization policy.

typedef uint8_t OpenPitSyncPolicy;
/**
 * Concurrent invocation of public methods on the same handle is safe.
 * Sequential cross-thread access is also safe. Use this when the engine is
 * shared across threads.
 */
#define OpenPitSyncPolicy_Full ((OpenPitSyncPolicy) 0)
/**
 * The handle stays on the OS thread that created it. Use this for
 * single-threaded embeddings where synchronization overhead must be zero.
 */
#define OpenPitSyncPolicy_Local ((OpenPitSyncPolicy) 1)
/**
 * Sequential cross-thread access on the same handle is safe; the caller pins
 * each account to a single processing chain (one queue or one worker at a
 * time). Concurrent invocation on the same handle is not supported in this
 * mode.
 */
#define OpenPitSyncPolicy_Account ((OpenPitSyncPolicy) 2)

OpenPitEngineBuilder

Opaque builder pointer used to assemble an engine instance.

Ownership:

• returned by openpit_create_engine_builder;
• owned by the caller until passed to openpit_destroy_engine_builder;
• consumed by openpit_engine_builder_build.

typedef struct OpenPitEngineBuilder OpenPitEngineBuilder;

OpenPitEngine

Opaque engine pointer.

The engine stores policies and mutable risk state. The caller owns the pointer until openpit_destroy_engine.

typedef struct OpenPitEngine OpenPitEngine;

OpenPitPretradePreTradeRequest

Opaque pointer for a deferred pre-trade request.

This is returned by openpit_engine_start_pre_trade. It can be executed once with openpit_pretrade_pre_trade_request_execute or discarded with openpit_destroy_pretrade_pre_trade_request.

typedef struct OpenPitPretradePreTradeRequest OpenPitPretradePreTradeRequest;

OpenPitPretradePreTradeReservation

Opaque reservation pointer returned by a successful pre-trade check.

A reservation represents resources that have been tentatively locked. The caller must resolve it exactly once by calling openpit_pretrade_pre_trade_reservation_commit, openpit_pretrade_pre_trade_reservation_rollback, or openpit_destroy_pretrade_pre_trade_reservation.

typedef struct OpenPitPretradePreTradeReservation
    OpenPitPretradePreTradeReservation;

OpenPitPretradePreTradeLock

Price-lock snapshot returned from a reservation.

typedef struct OpenPitPretradePreTradeLock {
    OpenPitParamPriceOptional price;
} OpenPitPretradePreTradeLock;

OpenPitPretradeStatus

Result status for pre-trade operations.

typedef uint8_t OpenPitPretradeStatus;
/**
 * Order/request passed this stage; read the success out-pointer.
 */
#define OpenPitPretradeStatus_Passed ((OpenPitPretradeStatus) 0)
/**
 * Order/request was rejected; read the reject out-pointer.
 */
#define OpenPitPretradeStatus_Rejected ((OpenPitPretradeStatus) 1)
/**
 * Call failed due to invalid input; read the error out-pointer.
 */
#define OpenPitPretradeStatus_Error ((OpenPitPretradeStatus) 2)

OpenPitAccountAdjustmentBatchError

Batch rejection details returned by account-adjustment apply API.

Ownership:

• created by openpit_engine_apply_account_adjustment on Rejected;
• owned by the caller;
• released with openpit_destroy_account_adjustment_batch_error.

typedef struct OpenPitAccountAdjustmentBatchError
    OpenPitAccountAdjustmentBatchError;

openpit_create_engine_builder

Creates a new engine builder with the chosen synchronization policy.

Success:

• returns a non-null caller-owned builder object.

Error:

• returns null when sync_policy is not one of OpenPitSyncPolicy_Full (0), OpenPitSyncPolicy_Local (1), or OpenPitSyncPolicy_Account (2);
• if out_error is not null, writes a caller-owned OpenPitSharedString error handle that MUST be released with openpit_destroy_shared_string.

Cleanup:

• release the pointer with openpit_destroy_engine_builder if you stop before building;
• after a successful build the builder is consumed and must still be released with openpit_destroy_engine_builder.

OpenPitEngineBuilder * openpit_create_engine_builder(
    uint8_t sync_policy,
    OpenPitOutError out_error
);

openpit_destroy_engine_builder

Releases a builder pointer owned by the caller.

Contract:

• passing null is allowed;
• after this call the pointer is invalid;
• this function always succeeds.

void openpit_destroy_engine_builder(
    OpenPitEngineBuilder * builder
);

openpit_engine_builder_build

Finalizes a builder and creates an engine.

Success:

• returns a non-null engine pointer.

Error:

• returns null when builder is null, the builder was already consumed, or configuration is invalid;
• if out_error is not null, writes a caller-owned OpenPitSharedString error handle that MUST be released with openpit_destroy_shared_string.

Ownership:

• on success the returned engine pointer is owned by the caller and must be released with openpit_destroy_engine;
• the builder becomes consumed regardless of success and must not be reused.

OpenPitEngine * openpit_engine_builder_build(
    OpenPitEngineBuilder * builder,
    OpenPitOutError out_error
);

openpit_destroy_engine

Releases an engine pointer owned by the caller.

Contract:

• passing null is allowed;
• destroying the engine also releases any state and policies retained by that engine instance;
• this function always succeeds.

void openpit_destroy_engine(
    OpenPitEngine * engine
);

openpit_engine_start_pre_trade

Starts pre-trade processing and returns a deferred request pointer.

This stage validates whether the order can enter the full pre-trade flow.

Success:

• returns Passed when the order passed this stage; read out_request;
• returns Rejected when the order was rejected; read out_rejects if not null.

Error:

• returns Error when input pointers are invalid or the order payload cannot be decoded;
• on Error, if out_error is not null, it is filled with a caller-owned OpenPitSharedString that MUST be destroyed by the caller.

Cleanup:

• release a successful request with openpit_pretrade_pre_trade_request_execute or openpit_destroy_pretrade_pre_trade_request.

Reject ownership contract:

• on Rejected, a non-null OpenPitPretradeRejectList pointer is written to out_rejects if it is not null;
• the caller takes ownership and MUST release it with openpit_pretrade_destroy_reject_list; failing to do so leaks the heap allocation made inside this call;
• no thread-local state is involved, and the returned pointer is safe to read on any thread;
• on Passed and Error, null is written to out_rejects, and the caller must not call destroy in those cases.

Order lifetime contract:

• order is read as a borrowed view during this call;
• the operation snapshots that payload before returning, because the deferred request may outlive the source buffers.

OpenPitPretradeStatus openpit_engine_start_pre_trade(
    OpenPitEngine * engine,
    const OpenPitOrder * order,
    OpenPitPretradePreTradeRequest ** out_request,
    OpenPitPretradeRejectList ** out_rejects,
    OpenPitOutError out_error
);

openpit_engine_execute_pre_trade

Runs the complete pre-trade check in one call.

Success:

• returns Passed when the order passed this stage; read out_reservation;
• returns Rejected when the order was rejected is not null; read out_rejects.

Error:

• returns Error when input pointers are invalid or the order payload cannot be decoded;
• on Error, if out_error is not null, it is filled with a caller-owned OpenPitSharedString that MUST be destroyed by the caller.

Cleanup:

• release a successful reservation with openpit_pretrade_pre_trade_reservation_commit, openpit_pretrade_pre_trade_reservation_rollback, or openpit_destroy_pretrade_pre_trade_reservation.

Reject ownership contract:

• on Rejected, a non-null OpenPitPretradeRejectList pointer is written to out_rejects if it is not null;
• the caller takes ownership and MUST release it with openpit_pretrade_destroy_reject_list; failing to do so leaks the heap allocation made inside this call;
• no thread-local state is involved, and the returned pointer is safe to read on any thread;
• on Passed and Error, null is written to out_rejects, and the caller must not call destroy in those cases.

Order lifetime contract:

• order is read as a borrowed view during this call only;
• the operation does not retain any pointer into source memory after this function returns.

OpenPitPretradeStatus openpit_engine_execute_pre_trade(
    OpenPitEngine * engine,
    const OpenPitOrder * order,
    OpenPitPretradePreTradeReservation ** out_reservation,
    OpenPitPretradeRejectList ** out_rejects,
    OpenPitOutError out_error
);

openpit_pretrade_pre_trade_request_execute

Executes a deferred request returned by openpit_engine_start_pre_trade.

Success:

• returns Passed when the order passed this stage; read out_reservation;
• returns Rejected when the order was rejected and out_rejects is not null; read out_rejects.

Error:

• returns Error when input pointers are invalid or the order payload cannot be decoded;
• on Error, if out_error is not null, it is filled with a caller-owned OpenPitSharedString that MUST be destroyed by the caller.

Ownership:

• this call consumes the request object's content exactly once;
• after a successful or failed execute, the object itself may still be released with openpit_destroy_pretrade_pre_trade_request, but it cannot be executed again.

Reject ownership contract:

• on Rejected, a non-null OpenPitPretradeRejectList pointer is written to out_rejects if it is not null;
• the caller takes ownership and MUST release it with openpit_pretrade_destroy_reject_list; failing to do so leaks the heap allocation made inside this call;
• no thread-local state is involved, and the returned pointer is safe to read on any thread;
• on Passed and Error, null is written to out_rejects, and the caller must not call destroy in those cases.

OpenPitPretradeStatus openpit_pretrade_pre_trade_request_execute(
    OpenPitPretradePreTradeRequest * request,
    OpenPitPretradePreTradeReservation ** out_reservation,
    OpenPitPretradeRejectList ** out_rejects,
    OpenPitOutError out_error
);

openpit_destroy_pretrade_pre_trade_request

Releases a deferred request pointer owned by the caller.

Contract:

• passing null is allowed;
• destroying an unexecuted request abandons it without creating a reservation;
• this function always succeeds.

void openpit_destroy_pretrade_pre_trade_request(
    OpenPitPretradePreTradeRequest * request
);

openpit_pretrade_pre_trade_reservation_commit

Finalizes a reservation and applies the reserved state permanently.

This call is idempotent at the pointer level: if the reservation was already consumed, nothing happens. Passing null is allowed.

Contract:

• passing null is allowed;
• this function always succeeds.

void openpit_pretrade_pre_trade_reservation_commit(
    OpenPitPretradePreTradeReservation * reservation
);

openpit_pretrade_pre_trade_reservation_rollback

Cancels a reservation and releases the reserved state.

This call is idempotent at the pointer level: if the reservation was already consumed, nothing happens. Passing null is allowed.

Contract:

• passing null is allowed;
• this function always succeeds.

void openpit_pretrade_pre_trade_reservation_rollback(
    OpenPitPretradePreTradeReservation * reservation
);

openpit_pretrade_pre_trade_reservation_get_lock

Returns a snapshot of the lock attached to a reservation.

Contract:

• reservation must be a valid non-null pointer;
• violating the pointer contract aborts the call;
• this function never fails.

Lifetime contract:

• the returned snapshot is detached from the reservation state.

OpenPitPretradePreTradeLock openpit_pretrade_pre_trade_reservation_get_lock(
    const OpenPitPretradePreTradeReservation * reservation
);

openpit_destroy_pretrade_pre_trade_reservation

Releases a reservation pointer owned by the caller.

Contract:

• passing null is allowed;
• destroying an unresolved reservation triggers rollback of any pending mutations;
• callers that need explicit resolution should call commit or rollback first;
• this function always succeeds.

void openpit_destroy_pretrade_pre_trade_reservation(
    OpenPitPretradePreTradeReservation * reservation
);

openpit_engine_apply_execution_report

Applies an execution report to engine state.

Returns true on success, false on error.

Success:

• returns true;
• if out_blocks is not null and at least one policy entered a blocked state, writes a caller-owned OpenPitPretradeAccountBlockList pointer; release it with openpit_pretrade_destroy_account_block_list;
• if out_blocks is not null and no policy blocked, writes null.

Error:

• returns false when input pointers are invalid or the report payload cannot be decoded;
• if out_error is not null, writes a caller-owned OpenPitSharedString error handle that MUST be released with openpit_destroy_shared_string.

Lifetime contract:

• report is read as a borrowed view during this call only;
• the operation does not retain any pointer into source memory after this function returns.

bool openpit_engine_apply_execution_report(
    OpenPitEngine * engine,
    const OpenPitExecutionReport * report,
    OpenPitPretradeAccountBlockList ** out_blocks,
    OpenPitOutError out_error
);

openpit_destroy_account_adjustment_batch_error

Releases a batch-error object returned by account-adjustment apply.

Contract:

• passing null is allowed;
• this function always succeeds.

void openpit_destroy_account_adjustment_batch_error(
    OpenPitAccountAdjustmentBatchError * batch_error
);

openpit_account_adjustment_batch_error_get_failed_adjustment_index

Returns the failing adjustment index from a batch error.

Contract:

• batch_error must be a valid non-null pointer;
• this function never fails;
• violating the pointer contract aborts the call.

size_t openpit_account_adjustment_batch_error_get_failed_adjustment_index(
    const OpenPitAccountAdjustmentBatchError * batch_error
);

openpit_account_adjustment_batch_error_get_rejects

Returns a non-owning reject-list view from a batch error.

Contract:

• batch_error must be a valid non-null pointer;
• the returned pointer is valid while batch_error is alive;
• this function never fails;
• violating the pointer contract aborts the call.

const OpenPitPretradeRejectList *
openpit_account_adjustment_batch_error_get_rejects(
    const OpenPitAccountAdjustmentBatchError * batch_error
);

openpit_engine_apply_account_adjustment

Applies a batch of account adjustments to one account.

Success:

• returns OpenPitAccountAdjustmentApplyStatus::Applied when the batch was accepted and applied;
• returns OpenPitAccountAdjustmentApplyStatus::Rejected when the call itself completed normally but a policy rejected the batch; read out_reject.

Error:

• returns OpenPitAccountAdjustmentApplyStatus::Error when input pointers are invalid or some adjustment payload cannot be decoded;
• on Error, if out_error is not null, it is filled with a caller-owned OpenPitSharedString that MUST be destroyed by the caller.

Result handling:

• Applied means there is no reject object to clean up;
• Rejected stores batch error details in out_reject, the caller must release a returned object with openpit_destroy_account_adjustment_batch_error;
• rejects returned by openpit_account_adjustment_batch_error_get_rejects contain string views borrowed from the batch error and must not be used after the batch error is destroyed;
• when Error is returned, do not use any pointer from a previous unrelated call as if it belonged to this failure.

Lifetime contract:

• every adjustment entry from the contiguous input array is read as a borrowed view during this call only;
• release a returned batch error with openpit_destroy_account_adjustment_batch_error.

OpenPitAccountAdjustmentApplyStatus openpit_engine_apply_account_adjustment(
    OpenPitEngine * engine,
    OpenPitParamAccountId account_id,
    const OpenPitAccountAdjustment * adjustments,
    size_t adjustments_len,
    OpenPitAccountAdjustmentBatchError ** out_reject,
    OpenPitOutError out_error
);