|
dxFeed Graal Native SDK 3.13.0-rc2
|
The events of subscriptions received on the application's own thread, without callbacks. More...
Data Structures | |
| struct | dxfg_v4_event_queue_t |
| The handle of an event queue (dxfg_v4_EventQueue_new()). More... | |
| struct | dxfg_v4_tagged_event_list |
| A list of events with a tag for each: the list returned by dxfg_v4_EventQueue_pollTagged(). More... | |
Macros | |
| #define | DXFG_EVENT_QUEUE_NO_EVENTS ((int32_t)1) |
| The result of dxfg_v4_EventQueue_poll() when no events arrived before the timeout or the queue was woken up, or when only the work of the models and the collector on the queue ran. | |
| #define | DXFG_EVENT_QUEUE_CLOSED ((int32_t)2) |
| The result of dxfg_v4_EventQueue_poll() when the queue is closed. | |
Typedefs | |
| typedef struct dxfg_v4_event_queue_t | dxfg_v4_event_queue_t |
| The handle of an event queue (dxfg_v4_EventQueue_new()). | |
| typedef struct dxfg_v4_tagged_event_list | dxfg_v4_tagged_event_list |
| A list of events with a tag for each: the list returned by dxfg_v4_EventQueue_pollTagged(). | |
| typedef enum dxfg_v4_ready_signal_kind_t | dxfg_v4_ready_signal_kind_t |
| The kind of the OS object that is the ready signal of an event queue (dxfg_v4_EventQueue_setReadySignal()). | |
Enumerations | |
| enum | dxfg_v4_ready_signal_kind_t { DXFG_V4_READY_SIGNAL_NONE = 0 , DXFG_V4_READY_SIGNAL_FD = 1 , DXFG_V4_READY_SIGNAL_WINDOWS_EVENT = 2 } |
| The kind of the OS object that is the ready signal of an event queue (dxfg_v4_EventQueue_setReadySignal()). More... | |
The events of subscriptions received on the application's own thread, without callbacks.
The application polls an event queue (dxfg_v4_EventQueue_poll(), dxfg_v4_EventQueue_pollTagged()) on a thread of its own: the call waits for events and returns them as a list. No thread of the SDK calls the application, which suits the languages that cannot take a call from a foreign thread.
A queue has the subscriptions attached to it as its sources:
An attached subscription gets an executor of the queue (see dxfg_v4_DXFeedSubscription_setExecutor()): the SDK retrieves the events from its buffers only when a poll runs, on the polling thread. So the queue keeps no copy of the events, and until the next poll, as with a listener that is slow to return:
The models and the instrument profile collector run on the queue too: give them the executor of a shared queue (dxfg_v4_EventQueue_getExecutor()), e.g. with dxfg_v4_IndexedTxModel_Builder_withExecutor(), dxfg_v4_IndexedEventModel_setExecutor() or dxfg_v4_InstrumentProfileCollector_setExecutor(). Their listeners are then called by the polls, on the polling thread, between the events of the subscriptions. A poll that ran their work and has no events returns DXFG_EVENT_QUEUE_NO_EVENTS at once, so DXFG_EVENT_QUEUE_NO_EVENTS also means that the listeners of the models may have been called. Their own data is not in the list: it reaches their listeners. Limits:
Executors:
Rules:
A poll ends when events arrive, when the work of the models has run, when the timeout elapses, when the queue is woken up (dxfg_v4_EventQueue_wakeUp()) and when the queue is closed. The queue is closed by dxfg_v4_EventQueue_close(), by the release of the last handle of the queue and of its executor, by the close of the subscription of a bound queue, by dxfg_v4_NativeListener_deactivateAll() and by dxfg_v4_system_shutdown(); the last two also close the queues created after them. A closed queue runs the work posted to it at once, on the posting thread, without calling any listener of the application: from then on the queue, its models and its collector call nothing back, while their objects stay usable until the application closes them. The events of a closed queue are discarded and counted as dropped. Closing an endpoint does not close a queue and does not end a poll: an application that closes the endpoints itself should poll with a finite timeout. While an open queue holds events that no poll has returned, dxfg_v4_DXEndpoint_closeAndAwaitTermination() of the endpoint of an attached subscription waits until the queue is polled or closed. dxfg_v4_DXFeed_detachSubscriptionAndClear() of an attached subscription does not wait for a poll: the events that are delivered while it runs arrive in the poll in progress or the next one, and the work of the other subscriptions and of the models stays in the queue.
Ready signal (experimental): a host with an event loop gives the queue an OS object of its own, and the SDK makes the object ready whenever the queue has work. The loop waits for the object and polls with the timeout 0 on its own thread, so the host keeps no thread that waits in a poll (dxfg_v4_EventQueue_setReadySignal(); the feature DXFG_V4_FEATURE_EVENT_QUEUE_READY_SIGNAL). The object is a file descriptor on Linux, macOS and iOS (an eventfd, or the write end of a pipe) and an event on Windows. The contract of the host:
An epoll loop on Linux:
Python asyncio on Linux and macOS: make the object (os.eventfd(0, os.EFD_NONBLOCK), or os.pipe() and os.set_blocking(write_end, False)), pass its descriptor to the function, and loop.add_reader(fd, on_ready) with a callback that reads the object and polls with the timeout 0.
A Windows host creates an auto-reset event with CreateEventW(NULL, FALSE, FALSE, NULL), passes it as (int64_t)(intptr_t)handle with DXFG_V4_READY_SIGNAL_WINDOWS_EVENT, and waits for it on a thread of the pool with RegisterWaitForSingleObject(), whose callback posts a message to the loop (or with WaitForSingleObject() or MsgWaitForMultipleObjects() in its own loop); the poll runs on the loop's thread. After the loop sees DXFG_EVENT_QUEUE_CLOSED, it calls UnregisterWaitEx() and then CloseHandle().
The functions are functions of the SDK: there are no QD methods that they call.
| #define DXFG_EVENT_QUEUE_CLOSED ((int32_t)2) |
The result of dxfg_v4_EventQueue_poll() when the queue is closed.
The value is 2. It is not an error: the list is NULL and no exception is pending. Every later poll returns it at once.
| #define DXFG_EVENT_QUEUE_NO_EVENTS ((int32_t)1) |
The result of dxfg_v4_EventQueue_poll() when no events arrived before the timeout or the queue was woken up, or when only the work of the models and the collector on the queue ran.
The value is 1. It is not an error: the list is NULL and no exception is pending.
| typedef struct dxfg_v4_event_queue_t dxfg_v4_event_queue_t |
The handle of an event queue (dxfg_v4_EventQueue_new()).
| typedef enum dxfg_v4_ready_signal_kind_t dxfg_v4_ready_signal_kind_t |
The kind of the OS object that is the ready signal of an event queue (dxfg_v4_EventQueue_setReadySignal()).
The value is an int of the C ABI. New kinds may be added.
| typedef struct dxfg_v4_tagged_event_list dxfg_v4_tagged_event_list |
A list of events with a tag for each: the list returned by dxfg_v4_EventQueue_pollTagged().
Its first two fields are those of dxfg_v4_event_type_list, so the same code can read the events. Release it with dxfg_v4_tagged_event_list_release(), not with dxfg_v4_event_type_list_release() (the tags would leak).
The kind of the OS object that is the ready signal of an event queue (dxfg_v4_EventQueue_setReadySignal()).
The value is an int of the C ABI. New kinds may be added.
| int32_t dxfg_v4_EventQueue_attach | ( | graal_isolatethread_t * | thread, |
| dxfg_v4_event_queue_t * | queue, | ||
| dxfg_v4_subscription_t * | sub, | ||
| int64_t | tag ) |
Attaches the subscription to the shared queue: its events go to the polls of the queue with the tag.
Attach it before the symbols are added to a subscription attached to a feed (QD refuses a listener then); a detached subscription may already have symbols, but then add its event listeners before attaching it. The executor of the queue for this subscription stays its executor for the life of the subscription. The subscription leaves the queue only by being closed. A closed subscription, or a subscription attached to a closed queue, is attached as left: its events are discarded and counted as dropped.
| [in] | thread | The current GraalVM Isolate's thread. |
| [in] | queue | The queue, created by dxfg_v4_EventQueue_create(). |
| [in] | sub | The subscription; it must have no executor and no queue. A subscription of any endpoint may be attached. |
| [in] | tag | The tag of the events of the subscription in dxfg_v4_EventQueue_pollTagged(); need not be unique. |
| int32_t dxfg_v4_EventQueue_close | ( | graal_isolatethread_t * | thread, |
| dxfg_v4_event_queue_t * | queue ) |
Closes the queue: the poll in progress returns the events it has already retrieved or DXFG_EVENT_QUEUE_CLOSED, every later poll returns DXFG_EVENT_QUEUE_CLOSED. The events that no poll has returned are discarded and counted as dropped, and so are the events of the subscriptions that arrive later. The pending work of the subscriptions, the models and the collector runs on the calling thread without calling any listener of the application, and their later work runs at once on the posting thread the same way. The function does not wait for the polls in progress. Closing a closed queue does nothing (if the queue had a ready signal, the call returns once the SDK no longer writes to its object).
Releasing the last handle of the queue and of its executor (dxfg_v4_JavaObjectHandler_release()) closes it as well.
| [in] | thread | The current GraalVM Isolate's thread. |
| [in] | queue | The queue. |
| int32_t dxfg_v4_EventQueue_create | ( | graal_isolatethread_t * | thread, |
| DXFG_OUT dxfg_v4_event_queue_t ** | queue ) |
Creates a shared event queue with no subscription: attach them with dxfg_v4_EventQueue_attach(), and give its executor (dxfg_v4_EventQueue_getExecutor()) to the models and the collector. A queue with nothing attached stays open, and its polls wait as usual.
| [in] | thread | The current GraalVM Isolate's thread. |
| [out] | queue | The pointer to the variable that receives the queue (release it with dxfg_v4_JavaObjectHandler_release(); the release of the last handle of the queue and of its executor closes it); must not be NULL. |
| int32_t dxfg_v4_EventQueue_getDroppedEvents | ( | graal_isolatethread_t * | thread, |
| dxfg_v4_event_queue_t * | queue, | ||
| DXFG_OUT int64_t * | droppedEvents ) |
Returns the number of the events of the attached subscriptions that were lost: the events that the SDK dropped as of the last retrieval (see DXFeedSubscription.getTotalDroppedEvents(); the last number for a closed subscription), plus the events that the queue dropped itself (a batch that failed to convert, the events of a closed queue or of a closed subscription). The number never decreases.
If the number grew since the previous poll, events were lost before the events that the last poll returned. For the indexed and time-series events (e.g. Order, Candle) the state built from the earlier events is then incomplete: subscribe again, or wait for the next snapshot. The number is one for the whole queue: to tell which subscription lost events, compare dxfg_v4_DXFeedSubscription_getTotalDroppedEvents() of each.
| [in] | thread | The current GraalVM Isolate's thread. |
| [in] | queue | The queue. |
| [out] | droppedEvents | The pointer to the variable that receives the number; must not be NULL. |
| int32_t dxfg_v4_EventQueue_getExecutor | ( | graal_isolatethread_t * | thread, |
| dxfg_v4_event_queue_t * | queue, | ||
| DXFG_OUT dxfg_v4_executor_t ** | executor ) |
Returns the executor of the shared queue: the work posted to it runs inside the polls, on the polling thread. Give it to the models, the collector, the endpoint builder or the asynchronous promise handlers whose listeners must run on the polling thread (see the group description for the limits).
A handle of the executor keeps the queue open as a handle of the queue does. The executor of a closed queue runs the work at once, on the posting thread, without calling any listener of the application.
| [in] | thread | The current GraalVM Isolate's thread. |
| [in] | queue | The queue, created by dxfg_v4_EventQueue_create(). |
| [out] | executor | The pointer to the variable that receives the executor (release it with dxfg_v4_JavaObjectHandler_release()); must not be NULL. |
| int32_t dxfg_v4_EventQueue_new | ( | graal_isolatethread_t * | thread, |
| dxfg_v4_subscription_t * | sub, | ||
| DXFG_OUT dxfg_v4_event_queue_t ** | queue ) |
Creates an event queue bound to the subscription: the subscription is attached with the tag 0, the queue closes when the subscription closes, and dxfg_v4_EventQueue_attach() and dxfg_v4_EventQueue_getExecutor() fail on it with IllegalStateException.
Create it before the symbols are added to a subscription attached to a feed (QD refuses a listener then); a detached subscription may already have symbols, but then add its event listeners before the queue. The executor of the queue stays the executor of the subscription for the life of the subscription, also after the queue is closed.
| [in] | thread | The current GraalVM Isolate's thread. |
| [in] | sub | The subscription; it must have no executor and no queue. |
| [out] | queue | The pointer to the variable that receives the queue (release it with dxfg_v4_JavaObjectHandler_release(), which also closes it); must not be NULL. |
| int32_t dxfg_v4_EventQueue_poll | ( | graal_isolatethread_t * | thread, |
| dxfg_v4_event_queue_t * | queue, | ||
| int64_t | timeoutInMilliseconds, | ||
| int32_t | limit, | ||
| DXFG_OUT dxfg_v4_event_type_list ** | events ) |
Waits for the events of the attached subscriptions and returns them, without their tags (see dxfg_v4_EventQueue_pollTagged()).
The SDK retrieves the events on the calling thread and calls the event listeners of the subscriptions, and the listeners of the models and the collector on the queue, on it. After the first events, or after the first work of the models, the poll only completes the work that is already pending, so a steady flow does not keep it from returning. A batch may exceed the limit: the limit stops the retrieval, it does not split it. The limit counts the events only. The events of one subscription keep their order.
Compare dxfg_v4_EventQueue_getDroppedEvents() after each poll to detect a gap before the returned events.
If the events cannot be converted to the C structures, or an event listener of the subscription fails during the poll, the function fails, the events it has retrieved are dropped and counted, and the next poll continues with the next events.
| [in] | thread | The current GraalVM Isolate's thread. |
| [in] | queue | The queue. |
| [in] | timeoutInMilliseconds | How long to wait for events: 0 returns at once; a negative value, or one above INT64_MAX / 1000000 (about 292 years), waits until events arrive, the queue is woken up or closed. |
| [in] | limit | The number of events after which no more events are retrieved, 0 for no limit; must not be negative. |
| [out] | events | The pointer to the variable that receives the list of events (release it with dxfg_v4_event_type_list_release()), or NULL if the result is not 0; must not be NULL. |
| int32_t dxfg_v4_EventQueue_pollTagged | ( | graal_isolatethread_t * | thread, |
| dxfg_v4_event_queue_t * | queue, | ||
| int64_t | timeoutInMilliseconds, | ||
| int32_t | limit, | ||
| DXFG_OUT dxfg_v4_tagged_event_list ** | events ) |
Waits for the events of the attached subscriptions and returns them with their tags.
The function works as dxfg_v4_EventQueue_poll() and has the same results; the list also holds the tag of each event, the one given to dxfg_v4_EventQueue_attach() for its subscription (0 for a queue created by dxfg_v4_EventQueue_new()).
| [in] | thread | The current GraalVM Isolate's thread. |
| [in] | queue | The queue. |
| [in] | timeoutInMilliseconds | How long to wait for events, as in dxfg_v4_EventQueue_poll(). |
| [in] | limit | The number of events after which no more events are retrieved, 0 for no limit; must not be negative. |
| [out] | events | The pointer to the variable that receives the list of events and tags (release it with dxfg_v4_tagged_event_list_release()), or NULL if the result is not 0; must not be NULL. |
| int32_t dxfg_v4_EventQueue_setReadySignal | ( | graal_isolatethread_t * | thread, |
| dxfg_v4_event_queue_t * | queue, | ||
| dxfg_v4_ready_signal_kind_t | kind, | ||
| int64_t | handle ) |
Sets, replaces or removes the ready signal of the queue: the OS object that the SDK makes ready whenever the queue has work, so that an event loop can poll with the timeout 0 on its own thread (see the group description for the contract of the host).
The host creates the object, owns it and closes it: the SDK never creates, duplicates or closes it. The queue signals when it gets work while it is armed (the events of a subscription, the work of a model or the collector, a wake-up, the close), and the signal disarms it; each poll arms it again and signals at once if work remains. If work is pending when the signal is set, it is signalled before the function returns. A signal without work is possible: its poll returns DXFG_EVENT_QUEUE_NO_EVENTS. A queue has one signal: a new one replaces the old one, and the SDK does not write to the old object after the function returns. DXFG_V4_READY_SIGNAL_NONE removes the signal; the close of the queue signals once more and then removes it. A signal set on a closed queue is written once, before the function returns, and not kept.
The write to a file descriptor is of 8 bytes and never blocks: the descriptor must be non-blocking (O_NONBLOCK; EFD_NONBLOCK for an eventfd) and open for writing (the write end of a pipe, not its read end), which the function checks with fcntl(F_GETFL). A failed write or SetEvent() is logged once per signal and does not fail anything else.
Reset the object before each poll, as the group description says; for example, with epoll on Linux:
Python asyncio loop.add_reader() and RegisterWaitForSingleObject() on Windows wait for the same objects (see the group description); the asyncio proactor loop and libuv on Windows cannot wait for them, so there the host keeps a thread that polls.
| [in] | thread | The current GraalVM Isolate's thread. |
| [in] | queue | The queue. |
| [in] | kind | The kind of the object: DXFG_V4_READY_SIGNAL_FD on Linux, macOS and iOS, DXFG_V4_READY_SIGNAL_WINDOWS_EVENT on Windows, or DXFG_V4_READY_SIGNAL_NONE to remove the signal. |
| [in] | handle | The file descriptor, or (int64_t)(intptr_t)HANDLE of the event; ignored for DXFG_V4_READY_SIGNAL_NONE. |
| int32_t dxfg_v4_EventQueue_wakeUp | ( | graal_isolatethread_t * | thread, |
| dxfg_v4_event_queue_t * | queue ) |
Makes the poll in progress, or the next poll if none is in progress, return DXFG_EVENT_QUEUE_NO_EVENTS at once (a poll that has events returns them instead). The wake-up is used by one poll: several calls before a poll wake up one poll.
Use it to stop a thread that polls with a long or infinite timeout without closing the queue.
| [in] | thread | The current GraalVM Isolate's thread. |
| [in] | queue | The queue. |
| int32_t dxfg_v4_tagged_event_list_release | ( | graal_isolatethread_t * | thread, |
| dxfg_v4_tagged_event_list * | events ) |
Releases a list returned by dxfg_v4_EventQueue_pollTagged(): its events, its tags and the list itself.
Any thread attached to the isolate may call it, also after the queue, the subscriptions and the endpoint are gone.
| [in] | thread | The current GraalVM Isolate's thread. |
| [in] | events | The list; NULL does nothing. |