Marketdata

`OpenPitInstrumentId`

Stable instrument identifier for all FFI payloads.

typedef uint64_t OpenPitInstrumentId;

`OpenPitMarketDataInstrumentId`

Backwards-compatible market-data spelling of OpenPitInstrumentId.

typedef OpenPitInstrumentId OpenPitMarketDataInstrumentId;

`OpenPitMarketDataQuote`

Market snapshot value passed across the FFI boundary.

Every field is optional (is_set == false means the producer did not publish that field). Mirrors Quote.

typedef struct OpenPitMarketDataQuote {
    OpenPitParamPriceOptional mark;
    OpenPitParamPriceOptional bid;
    OpenPitParamPriceOptional ask;
} OpenPitMarketDataQuote;

`openpit_create_marketdata_quote`

Returns an empty quote with every field unset.

This function never fails.

OpenPitMarketDataQuote openpit_create_marketdata_quote(void);

`OpenPitMarketDataQuoteTtl`

Service-wide / per-instrument quote lifetime for FFI payloads.

is_infinite == true means quotes never expire on their own. Otherwise the quote expires secs + nanos after the push that wrote it. Mirrors QuoteTtl.

typedef struct OpenPitMarketDataQuoteTtl {
    uint64_t secs;
    uint32_t nanos;
    bool is_infinite;
} OpenPitMarketDataQuoteTtl;

`openpit_create_marketdata_quote_ttl_infinite`

Builds an infinite quote lifetime.

This function never fails.

OpenPitMarketDataQuoteTtl openpit_create_marketdata_quote_ttl_infinite(void);

`openpit_create_marketdata_quote_ttl_within`

Builds a finite quote lifetime of secs seconds plus nanos nanoseconds.

This function never fails.

OpenPitMarketDataQuoteTtl openpit_create_marketdata_quote_ttl_within(
    uint64_t secs,
    uint32_t nanos
);

`OpenPitMarketDataQuoteResolution`

Selects which quote buckets a read will consult, in order.

When the more-specific bucket has no quote, the read falls through to the next bucket permitted by this value.

typedef uint8_t OpenPitMarketDataQuoteResolution;

`OPENPIT_MARKET_DATA_QUOTE_RESOLUTION_ACCOUNT_ONLY`

Consult only the per-account bucket for the reading account.

#define OPENPIT_MARKET_DATA_QUOTE_RESOLUTION_ACCOUNT_ONLY \
    ((OpenPitMarketDataQuoteResolution) 0)

`OPENPIT_MARKET_DATA_QUOTE_RESOLUTION_ACCOUNT_THEN_GROUP`

Consult the per-account bucket, then fall back to the account's group bucket when the account bucket has no quote.

#define OPENPIT_MARKET_DATA_QUOTE_RESOLUTION_ACCOUNT_THEN_GROUP \
    ((OpenPitMarketDataQuoteResolution) 1)

`OPENPIT_MARKET_DATA_QUOTE_RESOLUTION_ACCOUNT_THEN_GROUP_THEN_DEFAULT`

Consult the per-account bucket, then the account's group bucket, then the default-group ("everyone-else") bucket, in that order.

#define OPENPIT_MARKET_DATA_QUOTE_RESOLUTION_ACCOUNT_THEN_GROUP_THEN_DEFAULT \
    ((OpenPitMarketDataQuoteResolution) 2)

`OpenPitMarketDataGetStatus`

Result of a market-data read.

typedef uint8_t OpenPitMarketDataGetStatus;
/**
 * A usable quote was found; `out_quote` was written.
 */
#define OpenPitMarketDataGetStatus_Found ((OpenPitMarketDataGetStatus) 0)
/**
 * The instrument is registered but no usable quote is available (never pushed
 * or cleared).
 */
#define OpenPitMarketDataGetStatus_Unavailable ((OpenPitMarketDataGetStatus) 1)
/**
 * The instrument id is not registered with the service.
 */
#define OpenPitMarketDataGetStatus_UnknownInstrument \
    ((OpenPitMarketDataGetStatus) 2)
/**
 * The selected quote exists but aged past its effective TTL; the stale quote
 * was written to `out_quote`.
 */
#define OpenPitMarketDataGetStatus_QuoteExpired ((OpenPitMarketDataGetStatus) 3)
/**
 * The account-group resolver reported `Failed`, so the reading account's group
 * is unknown and no bucket may be selected on its behalf.
 */
#define OpenPitMarketDataGetStatus_AccountGroupResolutionFailed \
    ((OpenPitMarketDataGetStatus) 4)
/**
 * The supplied quote-resolution selector is invalid.
 */
#define OpenPitMarketDataGetStatus_Error ((OpenPitMarketDataGetStatus) 255)

`OpenPitMarketDataRegisterStatus`

Result of a market-data registration or update.

Each operation returns only the subset of variants it can produce; see the per-function contract for the variants it may report.

typedef uint8_t OpenPitMarketDataRegisterStatus;
/**
 * The operation succeeded; any associated output was written.
 */
#define OpenPitMarketDataRegisterStatus_Ok ((OpenPitMarketDataRegisterStatus) 0)
/**
 * The instrument is already registered with the service.
 */
#define OpenPitMarketDataRegisterStatus_AlreadyRegistered \
    ((OpenPitMarketDataRegisterStatus) 1)
/**
 * The supplied id is already registered with the service.
 */
#define OpenPitMarketDataRegisterStatus_DuplicateId \
    ((OpenPitMarketDataRegisterStatus) 2)
/**
 * The supplied instrument is already registered under a different id.
 */
#define OpenPitMarketDataRegisterStatus_DuplicateInstrument \
    ((OpenPitMarketDataRegisterStatus) 3)
/**
 * The supplied instrument id is not registered with the service.
 */
#define OpenPitMarketDataRegisterStatus_UnknownInstrument \
    ((OpenPitMarketDataRegisterStatus) 4)
/**
 * A boundary failure occurred (null pointer or an invalid payload); when
 * `out_error` is not null, a caller-owned error string was written.
 */
#define OpenPitMarketDataRegisterStatus_Error \
    ((OpenPitMarketDataRegisterStatus) 5)
/**
 * A targeted push (`push_for`) was called with both the account list and the
 * group list empty.
 */
#define OpenPitMarketDataRegisterStatus_NoTarget \
    ((OpenPitMarketDataRegisterStatus) 6)

`OpenPitMarketDataService`

Opaque shared market-data service handle.

Duplicate it with openpit_marketdata_service_clone to hand the same service to both a policy and a feed.

typedef struct OpenPitMarketDataService OpenPitMarketDataService;

`OpenPitMarketDataAccountGroupResolution`

Outcome of one account-group resolver invocation.

The caller must distinguish "this account has no group" from "the group could not be determined". Reporting a failure as None would silently move the read onto the default-group bucket and bypass every group-scoped rule.

typedef uint8_t OpenPitMarketDataAccountGroupResolution;
/**
 * The account belongs to no group; `out_account_group_id` is untouched.
 *
 * Zero preserves the previous callback's `false` meaning.
 */
#define OpenPitMarketDataAccountGroupResolution_NoGroup \
    ((OpenPitMarketDataAccountGroupResolution) 0)
/**
 * The account belongs to a group; `out_account_group_id` was written.
 *
 * One preserves the previous callback's `true` meaning.
 */
#define OpenPitMarketDataAccountGroupResolution_Found \
    ((OpenPitMarketDataAccountGroupResolution) 1)
/**
 * The group could not be determined. The enclosing read fails as a whole with
 * `AccountGroupResolutionFailed` and no quote is produced.
 */
#define OpenPitMarketDataAccountGroupResolution_Failed \
    ((OpenPitMarketDataAccountGroupResolution) 2)

`OpenPitMarketDataAccountGroupResolver`

Resolves the reading account's group on demand.

Writes the group id to out_account_group_id and returns Found when the account belongs to a group, NoGroup when it has none, and Failed when the group could not be determined. Invoked lazily by openpit_marketdata_service_get - only when the resolution mode would consult the group or default-group bucket and the per-account bucket has no quote.

Only NoGroup (0), Found (1), and Failed (2) are valid return values. Returning any other byte is an error and is handled as Failed: the enclosing read fails rather than falling through to a group bucket the callback never named.

The function pointer must not be null; see the contract on openpit_marketdata_service_get.

typedef uint8_t (*OpenPitMarketDataAccountGroupResolver)(
    void * user_data,
    OpenPitParamAccountGroupId * out_account_group_id
);

`openpit_create_marketdata_service`

Creates a market-data service with the chosen synchronization mode.

mode uses the same byte convention as openpit_create_engine_builder:

0 = None (no internal synchronization: no-op locks, zero overhead, single-threaded use only);
1 = Full (full synchronization: real RwLock, safe for a concurrent quote feed).

Only None (0) and Full (1) are valid for a market-data service. Passing 2 (Account) or any other byte is an error.

Success:

returns a non-null caller-owned OpenPitMarketDataService handle.

Error:

returns null when mode is not 0 or 1; if out_error is not null, writes a caller-owned OpenPitSharedString error handle that MUST be released with openpit_destroy_shared_string.

Cleanup:

the returned service handle MUST be released with openpit_destroy_marketdata_service exactly once.

OpenPitMarketDataService * openpit_create_marketdata_service(
    uint8_t mode,
    OpenPitMarketDataQuoteTtl default_ttl,
    OpenPitOutError out_error
);

`openpit_destroy_marketdata_service`

Releases a market-data service handle.

Contract:

passing null is allowed;
releases this handle; the underlying service stays alive while other handles to it exist;
after this call the pointer is invalid;
this function always succeeds.

void openpit_destroy_marketdata_service(
    OpenPitMarketDataService * service
);

`openpit_marketdata_service_clone`

Returns a new handle referring to the same market-data service.

Use this to hand the same service to a policy and a feed.

Success:

returns a non-null caller-owned handle to the same service.

Error:

returns null when service is null.

Cleanup:

the returned handle MUST be released with openpit_destroy_marketdata_service exactly once.

OpenPitMarketDataService * openpit_marketdata_service_clone(
    const OpenPitMarketDataService * service
);

`openpit_marketdata_service_register`

Registers instrument with the service-wide default TTL.

Status:

Ok: registered; the auto-assigned id was written to out_id;
AlreadyRegistered: the instrument is already registered;
Error: service/out_id is null or the instrument payload is invalid; if out_error is not null, a caller-owned OpenPitSharedString error handle was written that MUST be released with openpit_destroy_shared_string.

OpenPitMarketDataRegisterStatus openpit_marketdata_service_register(
    const OpenPitMarketDataService * service,
    const OpenPitInstrument * instrument,
    OpenPitMarketDataInstrumentId * out_id,
    OpenPitOutError out_error
);

`openpit_marketdata_service_register_with_ttl`

Registers instrument with a per-instrument TTL override.

Behaves like openpit_marketdata_service_register otherwise.

OpenPitMarketDataRegisterStatus openpit_marketdata_service_register_with_ttl(
    const OpenPitMarketDataService * service,
    const OpenPitInstrument * instrument,
    OpenPitMarketDataQuoteTtl ttl,
    OpenPitMarketDataInstrumentId * out_id,
    OpenPitOutError out_error
);

`openpit_marketdata_service_register_with_id`

Registers instrument under the caller-supplied instrument_id with the service-wide default TTL.

Status:

Ok: registered; instrument_id was written to out_id;
DuplicateInstrument: the instrument name is already registered under a different id;
DuplicateId: instrument_id is already registered;
Error: service/out_id is null or the instrument payload is invalid; if out_error is not null, a caller-owned OpenPitSharedString error handle was written.

OpenPitMarketDataRegisterStatus openpit_marketdata_service_register_with_id(
    const OpenPitMarketDataService * service,
    const OpenPitInstrument * instrument,
    OpenPitMarketDataInstrumentId instrument_id,
    OpenPitMarketDataInstrumentId * out_id,
    OpenPitOutError out_error
);

`openpit_marketdata_service_register_with_id_and_ttl`

Registers instrument under the caller-supplied instrument_id with a per-instrument TTL override.

Behaves like openpit_marketdata_service_register_with_id otherwise.

OpenPitMarketDataRegisterStatus
openpit_marketdata_service_register_with_id_and_ttl(
    const OpenPitMarketDataService * service,
    const OpenPitInstrument * instrument,
    OpenPitMarketDataInstrumentId instrument_id,
    OpenPitMarketDataQuoteTtl ttl,
    OpenPitMarketDataInstrumentId * out_id,
    OpenPitOutError out_error
);

`openpit_marketdata_service_set_account_ttl`

Pins the service-level TTL for account_id.

Applies to every instrument for account_id that does not have a more specific instrument × account TTL cell.

Contract:

service must be a valid non-null handle; passing null aborts the call;
this function never fails.

void openpit_marketdata_service_set_account_ttl(
    const OpenPitMarketDataService * service,
    OpenPitParamAccountId account_id,
    OpenPitMarketDataQuoteTtl ttl
);

`openpit_marketdata_service_clear_account_ttl`

Reverts the service-level TTL for account_id back to "inherit".

Contract:

service must be a valid non-null handle; passing null aborts the call;
this function never fails.

void openpit_marketdata_service_clear_account_ttl(
    const OpenPitMarketDataService * service,
    OpenPitParamAccountId account_id
);

`openpit_marketdata_service_set_account_group_ttl`

Pins the service-level TTL for account_group_id.

Pass OPENPIT_DEFAULT_ACCOUNT_GROUP (0) to set the service-level default-group TTL.

Contract:

service must be a valid non-null handle; passing null aborts the call;
this function never fails.

void openpit_marketdata_service_set_account_group_ttl(
    const OpenPitMarketDataService * service,
    OpenPitParamAccountGroupId account_group_id,
    OpenPitMarketDataQuoteTtl ttl
);

`openpit_marketdata_service_clear_account_group_ttl`

Reverts the service-level TTL for account_group_id back to "inherit".

Pass OPENPIT_DEFAULT_ACCOUNT_GROUP (0) to clear the default-group TTL.

Contract:

service must be a valid non-null handle; passing null aborts the call;
this function never fails.

void openpit_marketdata_service_clear_account_group_ttl(
    const OpenPitMarketDataService * service,
    OpenPitParamAccountGroupId account_group_id
);

`openpit_marketdata_service_set_instrument_ttl`

Updates the instrument-level TTL for an already-registered instrument.

This replaces the removed openpit_marketdata_service_set_ttl.

Status:

Ok: updated; the new TTL takes effect on the next read;
UnknownInstrument: instrument_id is not registered.

Contract:

service must be a valid non-null handle; passing null aborts the call.

OpenPitMarketDataRegisterStatus openpit_marketdata_service_set_instrument_ttl(
    const OpenPitMarketDataService * service,
    OpenPitMarketDataInstrumentId instrument_id,
    OpenPitMarketDataQuoteTtl ttl
);

`openpit_marketdata_service_clear_instrument_ttl`

Reverts the instrument-level TTL for instrument_id back to "inherit".

Status:

Ok: cleared;
UnknownInstrument: instrument_id is not registered.

Contract:

service must be a valid non-null handle; passing null aborts the call.

OpenPitMarketDataRegisterStatus openpit_marketdata_service_clear_instrument_ttl(
    const OpenPitMarketDataService * service,
    OpenPitMarketDataInstrumentId instrument_id
);

`openpit_marketdata_service_set_instrument_account_ttl`

Pins the instrument × account TTL cell for (instrument_id, account_id).

This is the highest-priority TTL tier (overrides all group and instrument-level cells for this account).

Status:

Ok: pinned;
UnknownInstrument: instrument_id is not registered.

Contract:

service must be a valid non-null handle; passing null aborts the call.

OpenPitMarketDataRegisterStatus
openpit_marketdata_service_set_instrument_account_ttl(
    const OpenPitMarketDataService * service,
    OpenPitMarketDataInstrumentId instrument_id,
    OpenPitParamAccountId account_id,
    OpenPitMarketDataQuoteTtl ttl
);

`openpit_marketdata_service_clear_instrument_account_ttl`

Reverts the instrument × account TTL cell for (instrument_id, account_id) back to "inherit".

Status:

Ok: cleared;
UnknownInstrument: instrument_id is not registered.

Contract:

service must be a valid non-null handle; passing null aborts the call.

OpenPitMarketDataRegisterStatus
openpit_marketdata_service_clear_instrument_account_ttl(
    const OpenPitMarketDataService * service,
    OpenPitMarketDataInstrumentId instrument_id,
    OpenPitParamAccountId account_id
);

`openpit_marketdata_service_set_instrument_account_group_ttl`

Pins the instrument × group TTL cell for (instrument_id, account_group_id).

Pass OPENPIT_DEFAULT_ACCOUNT_GROUP (0) for account_group_id to target the instrument's default-group TTL cell.

Status:

Ok: pinned;
UnknownInstrument: instrument_id is not registered.

Contract:

service must be a valid non-null handle; passing null aborts the call.

OpenPitMarketDataRegisterStatus
openpit_marketdata_service_set_instrument_account_group_ttl(
    const OpenPitMarketDataService * service,
    OpenPitMarketDataInstrumentId instrument_id,
    OpenPitParamAccountGroupId account_group_id,
    OpenPitMarketDataQuoteTtl ttl
);

`openpit_marketdata_service_clear_instrument_account_group_ttl`

Reverts the instrument × group TTL cell for (instrument_id, account_group_id) back to "inherit".

Pass OPENPIT_DEFAULT_ACCOUNT_GROUP (0) for account_group_id to clear the instrument's default-group TTL cell.

Status:

Ok: cleared;
UnknownInstrument: instrument_id is not registered.

Contract:

service must be a valid non-null handle; passing null aborts the call.

OpenPitMarketDataRegisterStatus
openpit_marketdata_service_clear_instrument_account_group_ttl(
    const OpenPitMarketDataService * service,
    OpenPitMarketDataInstrumentId instrument_id,
    OpenPitParamAccountGroupId account_group_id
);

`openpit_marketdata_service_clear`

Clears the stored quote for instrument_id.

Contract:

service must be a valid non-null handle; passing null aborts the call;
a no-op if instrument_id is not registered;
this function never fails.

void openpit_marketdata_service_clear(
    const OpenPitMarketDataService * service,
    OpenPitMarketDataInstrumentId instrument_id
);

`openpit_marketdata_service_push`

Publishes a quote for instrument_id, replacing the entire stored snapshot.

source_age_secs plus source_age_nanos is the time elapsed since the source observed the quote. The parts are normalized with saturating arithmetic.

Status:

Ok: the snapshot was replaced;
UnknownInstrument: instrument_id is not registered;
Error: service is null or quote carries an invalid price; if out_error is not null, a caller-owned OpenPitSharedString error handle was written.

OpenPitMarketDataRegisterStatus openpit_marketdata_service_push(
    const OpenPitMarketDataService * service,
    OpenPitMarketDataInstrumentId instrument_id,
    OpenPitMarketDataQuote quote,
    uint64_t source_age_secs,
    uint32_t source_age_nanos,
    OpenPitOutError out_error
);

`openpit_marketdata_service_push_for`

Publishes a quote for instrument_id into the per-account bucket of every account in account_ids and the per-group bucket of every group in account_group_ids, replacing each target's snapshot.

source_age_secs plus source_age_nanos is the time elapsed since the source observed the quote. The parts are normalized with saturating arithmetic.

A null pointer with a matching length of 0 is a valid empty list.

Status:

Ok: all targets were written;
UnknownInstrument: instrument_id is not registered;
NoTarget: both account_ids and account_group_ids are empty; use openpit_marketdata_service_push to write the default bucket;
Error: service is null or quote carries an invalid price; if out_error is not null, a caller-owned OpenPitSharedString error handle was written.

OpenPitMarketDataRegisterStatus openpit_marketdata_service_push_for(
    const OpenPitMarketDataService * service,
    OpenPitMarketDataInstrumentId instrument_id,
    OpenPitMarketDataQuote quote,
    uint64_t source_age_secs,
    uint32_t source_age_nanos,
    const OpenPitParamAccountId * account_ids,
    size_t account_ids_len,
    const OpenPitParamAccountGroupId * account_group_ids,
    size_t account_group_ids_len,
    OpenPitOutError out_error
);

`openpit_marketdata_service_push_by_instrument`

Publishes a quote for instrument, replacing the stored snapshot.

If instrument is unregistered, a named slot is created with the service-default TTL.

source_age_secs plus source_age_nanos is the time elapsed since the source observed the quote. The parts are normalized with saturating arithmetic.

Success:

returns true and writes the instrument's id to out_id.

Error:

returns false when service/out_id is null, the instrument payload is invalid, or quote carries an invalid price;
if out_error is not null, writes a caller-owned OpenPitSharedString error handle.

bool openpit_marketdata_service_push_by_instrument(
    const OpenPitMarketDataService * service,
    const OpenPitInstrument * instrument,
    OpenPitMarketDataQuote quote,
    uint64_t source_age_secs,
    uint32_t source_age_nanos,
    OpenPitMarketDataInstrumentId * out_id,
    OpenPitOutError out_error
);

`openpit_marketdata_service_get`

Reads the latest quote for (instrument_id, account_id) under the given resolution.

resolve_account_group is a required callback that supplies the reading account's group lazily - it is invoked only when the resolution mode would consult a group or default-group bucket and the per-account bucket has no quote. The callback receives the caller-supplied user_data context pointer and, when the account belongs to a group, writes the group id to out_account_group_id and returns Found; when the account has no group it returns NoGroup; when the group cannot be determined it returns Failed. Pass OPENPIT_DEFAULT_ACCOUNT_GROUP (0) to target the default group bucket.

resolution controls which buckets are consulted, in order, when the more-specific bucket has no quote.

Status:

Found: a usable quote was written to out_quote;
Unavailable: registered but no usable quote (never pushed or cleared);
UnknownInstrument: instrument_id is not registered;
QuoteExpired: selected quote aged past TTL; the stale quote was written to out_quote;
AccountGroupResolutionFailed: resolve_account_group returned Failed; out_quote is left untouched. A failed resolution is never degraded into "the account has no group", because that would silently move the read onto the default-group bucket;
Error: resolution is not one of the documented selector constants.

Contract:

service, resolve_account_group, and out_quote must be valid non-null pointers; passing null for any of them aborts the call.

OpenPitMarketDataGetStatus openpit_marketdata_service_get(
    const OpenPitMarketDataService * service,
    OpenPitMarketDataInstrumentId instrument_id,
    OpenPitParamAccountId account_id,
    OpenPitMarketDataAccountGroupResolver resolve_account_group,
    void * user_data,
    OpenPitMarketDataQuoteResolution resolution,
    OpenPitMarketDataQuote * out_quote
);

`openpit_marketdata_service_resolve`

Resolves instrument to its registered id.

Success:

returns true and writes the id to out_id when instrument is registered by name;
returns false (without writing out_id) when the instrument is not registered, the instrument payload is invalid, or service/out_id is null.

This call does not use out_error: a false result simply means "not resolved".

bool openpit_marketdata_service_resolve(
    const OpenPitMarketDataService * service,
    const OpenPitInstrument * instrument,
    OpenPitMarketDataInstrumentId * out_id
);