|
| 1 | +/* SPDX-License-Identifier: Apache-2.0 */ |
| 2 | +#ifndef PINEFORGE_LIVE_PARSER_H |
| 3 | +#define PINEFORGE_LIVE_PARSER_H |
| 4 | + |
| 5 | +#include <stddef.h> |
| 6 | +#include <stdint.h> |
| 7 | + |
| 8 | +#define PF_LIVE_PARSER_ABI_VERSION 1u |
| 9 | +#define PF_LIVE_PARSER_MAX_MESSAGE_BYTES (1024u * 1024u) |
| 10 | +#define PF_LIVE_PARSER_MAX_EVENTS 1024u |
| 11 | +#define PF_LIVE_PARSER_MAX_OUTPUT_BYTES (1024u * 1024u) |
| 12 | + |
| 13 | +#if defined(_WIN32) || defined(__CYGWIN__) |
| 14 | +#define PF_LIVE_PARSER_API __declspec(dllexport) |
| 15 | +#elif defined(__GNUC__) || defined(__clang__) |
| 16 | +#define PF_LIVE_PARSER_API __attribute__((visibility("default"))) |
| 17 | +#else |
| 18 | +#define PF_LIVE_PARSER_API |
| 19 | +#endif |
| 20 | + |
| 21 | +#ifdef __cplusplus |
| 22 | +extern "C" { |
| 23 | +#endif |
| 24 | + |
| 25 | +enum pf_live_parser_event_kind { |
| 26 | + PF_LIVE_PARSER_TICK = 1, |
| 27 | + PF_LIVE_PARSER_BAR = 2, |
| 28 | + PF_LIVE_PARSER_TIME = 3 |
| 29 | +}; |
| 30 | + |
| 31 | +/* ABI v1 is fixed-layout POD; a changed layout requires a new ABI version. |
| 32 | + * Initialize the whole struct to zero before assigning its active fields. |
| 33 | + * All timestamps are Unix milliseconds and must be nonnegative. |
| 34 | + * |
| 35 | + * TICK: timestamp, strictly positive source sequence, price and quantity. |
| 36 | + * BAR: timestamp is a confirmed one-minute bar's open, aligned to 60000ms; |
| 37 | + * open/high/low/close are positive finite prices; volume is finite >= 0. |
| 38 | + * TIME: timestamp is the provider's explicit completeness boundary, declaring |
| 39 | + * that no earlier ticks remain. A wall clock/heartbeat is not sufficient. |
| 40 | + * |
| 41 | + * reserved must be zero. Inactive fields are ignored and normalized to zero by |
| 42 | + * the host. Sequence continuity, mode and stream ordering are checked by the |
| 43 | + * runner across messages; parsers must preserve source sequence, never invent |
| 44 | + * a mutable counter. BAR/TIME do not use sequence. |
| 45 | + */ |
| 46 | +typedef struct pf_live_parser_event_v1 { |
| 47 | + uint32_t kind; |
| 48 | + uint32_t reserved; |
| 49 | + int64_t timestamp; |
| 50 | + uint64_t sequence; |
| 51 | + double open; |
| 52 | + double high; |
| 53 | + double low; |
| 54 | + double close; |
| 55 | + double volume; |
| 56 | + double price; |
| 57 | + double quantity; |
| 58 | +} pf_live_parser_event_v1_t; |
| 59 | + |
| 60 | +/* The event pointer is borrowed only until this callback returns. The callback |
| 61 | + * copies it synchronously and returns 0 on acceptance or -1 on failure. A plugin |
| 62 | + * MUST stop and propagate a callback failure; it must not retain callback/user |
| 63 | + * pointers, call concurrently, or emit after parse_message returns. |
| 64 | + */ |
| 65 | +typedef int (*pf_live_parser_emit_v1_fn)( |
| 66 | + const pf_live_parser_event_v1_t* event, void* user); |
| 67 | + |
| 68 | +PF_LIVE_PARSER_API uint32_t pf_live_parser_abi_version(void); |
| 69 | + |
| 70 | +/* Parse ONE complete provider message into zero or more ordered events. |
| 71 | + * message/config_json are length-delimited borrowed bytes, not NUL-terminated |
| 72 | + * strings. config_json is an immutable JSON object; it remains in host memory |
| 73 | + * and must not be logged or copied into normalized events. Heartbeats/control |
| 74 | + * messages may succeed with zero events. Malformed input MUST fail. |
| 75 | + * |
| 76 | + * Return 0 on success, -1 on any failure. Never throw across this C ABI. The |
| 77 | + * host stages events until success, so a failed message emits no partial output |
| 78 | + * to the strategy or journal. Limits: 1MiB message, 1024 events, 1MiB POD output. |
| 79 | + * With the v1 event size the event-count bound is the tighter output bound. |
| 80 | + * |
| 81 | + * REQUIRED: stateless and deterministic for identical (message, config) bytes. |
| 82 | + * No I/O, clock, random values, mutable globals or retained state may influence |
| 83 | + * output. The journal stores canonical normalized events, not parser state. |
| 84 | + * Providers requiring cross-message assembly/state need an upstream adapter. |
| 85 | + * Plugins are trusted native executable code, not sandboxed. The host cannot |
| 86 | + * enforce this contract against malicious code or recover from native crashes. |
| 87 | + */ |
| 88 | +PF_LIVE_PARSER_API int pf_live_parse_message( |
| 89 | + const char* message, size_t message_size, |
| 90 | + const char* config_json, size_t config_size, |
| 91 | + pf_live_parser_emit_v1_fn emit, void* user); |
| 92 | + |
| 93 | +#ifdef __cplusplus |
| 94 | +} /* extern "C" */ |
| 95 | +#endif |
| 96 | +#endif /* PINEFORGE_LIVE_PARSER_H */ |
0 commit comments