dxFeed Graal Native SDK 3.14.0
Loading...
Searching...
No Matches
Exceptions (v4)

The v4 functions and type names of the group Exceptions. Every function returns DXFG_EXECUTE_SUCCESSFULLY or DXFG_EXECUTE_FAIL and writes its result to a DXFG_OUT parameter, see The v4 functions. More...

Typedefs

typedef dxfg_stack_trace_element_t dxfg_v4_stack_trace_element_t
 An element of the stack trace of an exception: one frame, the same data as a Java StackTraceElement.
typedef dxfg_stack_trace_element_list dxfg_v4_stack_trace_element_list
 The stack trace of an exception: a list of its frames, the innermost call first.
typedef dxfg_exception_t dxfg_v4_exception_t
 An exception that was thrown by the Java side: the class, the message, the stack trace and the cause.

Functions

int32_t dxfg_v4_get_and_clear_thread_exception (graal_isolatethread_t *thread, DXFG_OUT dxfg_v4_exception_t **exception)
 Writes the exception of the last failed function call of the calling thread and clears it.
int32_t dxfg_v4_Exception_release (graal_isolatethread_t *thread, dxfg_v4_exception_t *exception)
 Releases an exception that was written by dxfg_v4_get_and_clear_thread_exception().

Detailed Description

The v4 functions and type names of the group Exceptions. Every function returns DXFG_EXECUTE_SUCCESSFULLY or DXFG_EXECUTE_FAIL and writes its result to a DXFG_OUT parameter, see The v4 functions.

Typedef Documentation

◆ dxfg_v4_exception_t

An exception that was thrown by the Java side: the class, the message, the stack trace and the cause.

It is returned by dxfg_get_and_clear_thread_exception_t() and owned by the caller: release it with dxfg_Exception_release(), which frees the structure, its strings, its stack trace and the whole chain of causes. Every pointer inside the structure belongs to it; copy what has to outlive the structure.

Javadoc

◆ dxfg_v4_stack_trace_element_list

The stack trace of an exception: a list of its frames, the innermost call first.

The structure belongs to the dxfg_exception_t that contains it and is freed with it by dxfg_Exception_release().

◆ dxfg_v4_stack_trace_element_t

An element of the stack trace of an exception: one frame, the same data as a Java StackTraceElement.

The structure and its strings belong to the dxfg_exception_t that contains it and are freed with it by dxfg_Exception_release(). A string that the Java side has no value for is NULL.

Javadoc

Function Documentation

◆ dxfg_v4_Exception_release()

int32_t dxfg_v4_Exception_release ( graal_isolatethread_t * thread,
dxfg_v4_exception_t * exception )

Releases an exception that was written by dxfg_v4_get_and_clear_thread_exception().

Frees the structure together with its strings, its stack trace and its whole chain of causes. A NULL pointer is ignored. Do not use the structure or the pointers inside it afterwards. Releasing the same exception twice is undefined behaviour, as for every release function.

Java: not applicable (the structure is allocated by the SDK outside the Java heap).

Parameters
[in]threadThe current GraalVM Isolate's thread.
[in]exceptionThe exception to release, or NULL.
Returns
DXFG_EXECUTE_SUCCESSFULLY (0): the function does not fail.

◆ dxfg_v4_get_and_clear_thread_exception()

int32_t dxfg_v4_get_and_clear_thread_exception ( graal_isolatethread_t * thread,
DXFG_OUT dxfg_v4_exception_t ** exception )

Writes the exception of the last failed function call of the calling thread and clears it.

Call it when a function returned DXFG_EXECUTE_FAIL to learn what went wrong. The exception is stored per thread: this function takes the exception of the thread that calls it (the thread parameter is not used to choose it), so call it on the thread on which the function failed. The stored exception is cleared by this call: a second call writes NULL until another function fails.

A function that completes successfully does not clear the stored exception, so call this function right after the error: otherwise it can return the exception of an earlier failure that was not taken. When several functions fail on a thread before the exception is taken, only the exception of the last failure is stored.

The function reads the stored exception, converts it and then clears it. If the conversion fails (e.g. there is no memory left), the function returns DXFG_EXECUTE_FAIL and the stored exception is replaced by the exception of the conversion. If exception is NULL, the function returns DXFG_EXECUTE_FAIL and the stored exception is replaced by an IllegalArgumentException.

Java: JNIThreadLocalPendingException.get() and JNIThreadLocalPendingException.clear() (GraalVM native image), the result is converted from Throwable.

Parameters
[in]threadThe current GraalVM Isolate's thread.
[out]exceptionThe pointer to the variable that receives the exception (release it with dxfg_v4_Exception_release()), or NULL if no exception is stored for the calling thread; must not be NULL.
Returns
DXFG_EXECUTE_SUCCESSFULLY (0) when the exception or NULL was written, DXFG_EXECUTE_FAIL (-1) when the function failed (call it again to get the reason).