dxFeed Graal Native SDK 3.16.0-rc1
Loading...
Searching...
No Matches
The v4 functions

The dxfg_v4_ functions: the operations of the older functions of the C API in one uniform form.

The dxfg_v4_ functions: the operations of the older functions of the C API in one uniform form.

A function of the C API that has a dxfg_v4_ twin is deprecated in favour of it. The twin is declared in a dxfg_v4_<area>.h header next to the header of the older function (dxfg_v4_api.h and dxfg_api.h include all of them). dxfg_free_strings() and dxfg_free_string_to_double_map_entries() have no twin and are deprecated: the v4 functions return lists, released by their dxfg_v4_<element>_list_release() functions. The deprecated functions are removed in 4.0.0, the next major release; their deprecation warnings name the functions to move to. A twin does the same as the older function, only its form differs:

  • It returns int32_t: DXFG_EXECUTE_SUCCESSFULLY (0) on success, DXFG_EXECUTE_FAIL (-1) on error. The status is the only error signal: after -1, dxfg_v4_get_and_clear_thread_exception() gives the exception. A successful call does not clear an exception left by an earlier failed call that was not taken, so take it right after the error. A function that waits may also return documented positive codes for outcomes that are not errors (e.g. DXFG_PROMISE_AWAIT_TIMED_OUT, DXFG_EVENT_QUEUE_NO_EVENTS).
  • It writes its result to the last parameter, marked DXFG_OUT: the caller passes the address of its own variable. The variable is written only if the function succeeds (dxfg_v4_DXFeed_getLastEvent() and dxfg_v4_DXFeed_getLastEvents() write NULL on error, as their older functions do); after an error its value must not be used. A NULL out pointer is an error (IllegalArgumentException), unless the parameter is documented as optional.
  • A NULL handle, string or list written to the out variable means "no value" (e.g. no session is found), it is never an error. A number is written as it is: -1 or 0 are ordinary values, not error markers.
  • It returns a collection as a list dxfg_v4_<element>_list (size and elements; elements of an empty list may be NULL), which is released with its dxfg_v4_<element>_list_release() function. A list that the caller builds and passes to a function stays the caller's: it is never passed to a release function.
  • Its name has no digit suffix: an overload is named by what it takes (e.g. dxfg_v4_TimePeriod_valueOfString()).
  • The types of its parameters have dxfg_v4_ names: typedefs of the older types with the same layout. The constants of the enumerations keep their names.

The dxfg_v4_ prefix names a generation of the C API, not a release of the SDK: the rules above hold for every function and type with this prefix, and later releases, major ones included, add functions with the same prefix. A new generation appears only when these rules change. It is named after the major release in which it becomes the only one: the v4 functions become the only ones in 4.0.0.

The v4 functions have two tiers:

  • A stable function keeps its name, parameters and behaviour. It changes only by deprecation (a new function replaces it, and the old one is marked DXFG_DEPRECATED), and it is removed only in a major release.
  • An experimental function is marked with DXFG_EXPERIMENTAL and listed on the page Experimental declarations. It may change or be removed in any minor release, also between the release candidates of one release. An incompatible change gives it a new name (named by what it takes, with no digit suffix) and increments the advanced revision (dxfg_v4_system_get_advanced_revision(), DXFG_V4_ADVANCED_REVISION), so a wrapper bound by name misses the old symbol instead of calling it with a changed signature. A compatible addition adds a feature (dxfg_v4_system_is_feature_supported()) and keeps the revision. A function promoted to stable keeps its name.

The experimental functions are the twins of the Java API that is experimental (@Experimental in QD, and the transaction models taken from the experimental Java API), and the functions of the advanced headers: the dxfg_v4_*.h headers that dxfg_v4_api.h does not include, each one included on its own. The twins came out in 3.12.0, before the tiers, and are experimental since 3.13.0; their older functions stay until 4.0.0, as the other deprecated functions do, and their deprecation messages say that the replacement is experimental. An advanced header may include the basic headers, never the other way round. The experimental event types say so in their descriptions; their structures are delivered as the other events are. Every declaration added after 3.12.0 names the release that added it (@since).

The older and the v4 functions can be mixed on the same objects: a handle, a string or a list that one of them returned can be passed to the other one and released by the release function of either.

The older functions that have twins are marked with DXFG_DEPRECATED, so the compilers warn where they are used. To compile code that still uses them without the warnings, define the macro empty before the headers are included: #define DXFG_DEPRECATED(message) in the code, or -DDXFG_DEPRECATED(message)= on the command line of GCC and Clang. With MSVC, the warning is C4996 (/wd4996 disables it).

A wrapper for another language builds on these rules: Wrapper guide states what it may rely on and must do (threads, ownership, outcomes, versioning, delivery), and the conformance kit that checks it.