dxFeed Graal Native SDK 3.16.0
Loading...
Searching...
No Matches
graal_isolate.h File Reference

The functions of GraalVM that create, attach to and tear down an isolate, the instance of the SDK in the process: graal_create_isolate(), graal_attach_thread(), graal_tear_down_isolate(), etc. More...

Go to the source code of this file.

Data Structures

struct  __graal_create_isolate_params_t
 The parameters of graal_create_isolate(). More...

Macros

#define NO_PROTECTION_DOMAIN   0
 The values of graal_create_isolate_params_t.pkey (protection domains, internal: leave it 0).
#define NEW_PROTECTION_DOMAIN   -1
 See NO_PROTECTION_DOMAIN.

Typedefs

typedef struct __graal_isolate_t graal_isolate_t
 An isolate: the instance of the SDK (its heap and Java state) in the process.
typedef struct __graal_isolatethread_t graal_isolatethread_t
 The state of one thread attached to an isolate: the first parameter (thread) of the SDK functions.
typedef unsigned long __graal_uword
 An unsigned integer of the size of a pointer: the type of the sizes in graal_create_isolate_params_t.
typedef struct __graal_create_isolate_params_t graal_create_isolate_params_t
 The parameters of graal_create_isolate(): see struct __graal_create_isolate_params_t.

Enumerations

enum  { __graal_create_isolate_params_version = 5 }
 The version of graal_create_isolate_params_t that this header declares (its version field). More...

Functions

int graal_create_isolate (graal_create_isolate_params_t *params, graal_isolate_t **isolate, graal_isolatethread_t **thread)
 Creates a new isolate and attaches the current thread to it.
int graal_attach_thread (graal_isolate_t *isolate, graal_isolatethread_t **thread)
 Attaches the current thread to the isolate.
graal_isolatethread_t * graal_get_current_thread (graal_isolate_t *isolate)
 Returns the isolate thread of the current thread in the isolate.
graal_isolate_t * graal_get_isolate (graal_isolatethread_t *thread)
 Returns the isolate of an isolate thread.
int graal_detach_thread (graal_isolatethread_t *thread)
 Detaches the isolate thread from its isolate and discards its state.
int graal_tear_down_isolate (graal_isolatethread_t *thread)
 Tears down the isolate of the isolate thread (which must still be attached): waits for the other attached threads to detach, then discards the objects, the threads and the other state of the isolate.
int graal_detach_all_threads_and_tear_down_isolate (graal_isolatethread_t *thread)
 Detaches all the threads that were started outside Java and attached to the isolate afterwards (including the current one), shuts down the threads started in Java and tears down the isolate (see graal_tear_down_isolate()).

Detailed Description

The functions of GraalVM that create, attach to and tear down an isolate, the instance of the SDK in the process: graal_create_isolate(), graal_attach_thread(), graal_tear_down_isolate(), etc.

native-image generates this header for the library of the SDK; the build of the SDK fails if the declarations here differ from the ones that its GraalVM generates, so only the comments are the SDK's. The x64 libraries (macOS x64 and the x86_64 slice of the iOS Simulator) are built with an older GraalVM, which declares version 4 of graal_create_isolate_params_t: the same fields, named _reserved_1, _reserved_2 and _reserved_3 instead of argc, argv and ignore_unrecognized_args; these libraries take the parameters of this header too. graal_isolate_dynamic.h declares the same functions as pointer types, for loading the library at run time.

An isolate has its own heap and its own Java state (the system properties, the endpoints, etc.): the handles of one isolate cannot be used in another. Every thread that calls the SDK must be attached to the isolate, and every function of the SDK takes the graal_isolatethread_t of the calling thread:

graal_isolate_t *isolate = NULL;
graal_isolatethread_t *thread = NULL;
if (graal_create_isolate(NULL, &isolate, &thread) != 0) { // the current thread is attached
return; // the reason is printed to stderr
}
// ... the SDK functions with the thread ...
// Another thread:
graal_isolatethread_t *other = NULL;
if (graal_attach_thread(isolate, &other) == 0) {
// ... the SDK functions with other ...
graal_detach_thread(other); // before the thread exits
}
// At the end (see dxfg_v4_system_shutdown()):
// ... release the remaining handles ...
struct __graal_isolate_t graal_isolate_t
An isolate: the instance of the SDK (its heap and Java state) in the process.
Definition graal_isolate.h:51
int graal_create_isolate(graal_create_isolate_params_t *params, graal_isolate_t **isolate, graal_isolatethread_t **thread)
Creates a new isolate and attaches the current thread to it.
int graal_detach_thread(graal_isolatethread_t *thread)
Detaches the isolate thread from its isolate and discards its state.
int graal_tear_down_isolate(graal_isolatethread_t *thread)
Tears down the isolate of the isolate thread (which must still be attached): waits for the other atta...
struct __graal_isolatethread_t graal_isolatethread_t
The state of one thread attached to an isolate: the first parameter (thread) of the SDK functions.
Definition graal_isolate.h:60
int graal_attach_thread(graal_isolate_t *isolate, graal_isolatethread_t **thread)
Attaches the current thread to the isolate.
int32_t dxfg_v4_system_shutdown(graal_isolatethread_t *thread)
Stops the calls of all the native listeners of this isolate, then closes all the endpoints and instru...

Macro Definition Documentation

◆ NEW_PROTECTION_DOMAIN

#define NEW_PROTECTION_DOMAIN   -1

◆ NO_PROTECTION_DOMAIN

#define NO_PROTECTION_DOMAIN   0

The values of graal_create_isolate_params_t.pkey (protection domains, internal: leave it 0).

Typedef Documentation

◆ __graal_uword

typedef unsigned long __graal_uword

An unsigned integer of the size of a pointer: the type of the sizes in graal_create_isolate_params_t.

◆ graal_create_isolate_params_t

◆ graal_isolate_t

typedef struct __graal_isolate_t graal_isolate_t

An isolate: the instance of the SDK (its heap and Java state) in the process.

The pointer is valid until the isolate is torn down; graal_attach_thread() and graal_get_current_thread() take it.

◆ graal_isolatethread_t

typedef struct __graal_isolatethread_t graal_isolatethread_t

The state of one thread attached to an isolate: the first parameter (thread) of the SDK functions.

It belongs to the thread that attached itself (graal_create_isolate(), graal_attach_thread()) and must not be used by other threads; it is valid until the thread detaches (graal_detach_thread()) or the isolate is torn down.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

The version of graal_create_isolate_params_t that this header declares (its version field).

Enumerator
__graal_create_isolate_params_version 

Function Documentation

◆ graal_attach_thread()

int graal_attach_thread ( graal_isolate_t * isolate,
graal_isolatethread_t ** thread )

Attaches the current thread to the isolate.

A thread must be attached before it calls the SDK, and it should detach (graal_detach_thread()) before it exits. If the thread is already attached, the call succeeds and returns its isolate thread.

Parameters
[in]isolateThe isolate.
[out]threadReceives the isolate thread of the current thread.
Returns
0 on success, a non-zero value on failure.

◆ graal_create_isolate()

int graal_create_isolate ( graal_create_isolate_params_t * params,
graal_isolate_t ** isolate,
graal_isolatethread_t ** thread )

Creates a new isolate and attaches the current thread to it.

Parameters
[in]paramsThe parameters (see graal_create_isolate_params_t), or NULL for the defaults.
[out]isolateReceives the isolate, if not NULL.
[out]threadReceives the isolate thread of the current thread, if not NULL.
Returns
0 on success, a non-zero value on failure (an invalid isolate argument prints the reason to stderr).

◆ graal_detach_all_threads_and_tear_down_isolate()

int graal_detach_all_threads_and_tear_down_isolate ( graal_isolatethread_t * thread)

Detaches all the threads that were started outside Java and attached to the isolate afterwards (including the current one), shuts down the threads started in Java and tears down the isolate (see graal_tear_down_isolate()).

None of the detached threads may be running Java code (an SDK function) when it is called or afterwards: that is undefined and likely fatal behavior. It blocks as graal_tear_down_isolate() does.

Parameters
[in]threadThe isolate thread of the current thread.
Returns
0 on success, a non-zero value on a (non-fatal) failure.

◆ graal_detach_thread()

int graal_detach_thread ( graal_isolatethread_t * thread)

Detaches the isolate thread from its isolate and discards its state.

No SDK function may be running on the isolate thread, and it must not be used afterwards.

Parameters
[in]threadThe isolate thread of the current thread.
Returns
0 on success, a non-zero value on failure.

◆ graal_get_current_thread()

graal_isolatethread_t * graal_get_current_thread ( graal_isolate_t * isolate)

Returns the isolate thread of the current thread in the isolate.

Parameters
[in]isolateThe isolate.
Returns
The isolate thread, or NULL if the current thread is not attached to the isolate or on another error.

◆ graal_get_isolate()

graal_isolate_t * graal_get_isolate ( graal_isolatethread_t * thread)

Returns the isolate of an isolate thread.

Parameters
[in]threadThe isolate thread.
Returns
The isolate, or NULL on error.

◆ graal_tear_down_isolate()

int graal_tear_down_isolate ( graal_isolatethread_t * thread)

Tears down the isolate of the isolate thread (which must still be attached): waits for the other attached threads to detach, then discards the objects, the threads and the other state of the isolate.

The call blocks while Java threads of the isolate run that do not stop on Thread.interrupt(). The threads of an open endpoint do not, so close the endpoints first with dxfg_v4_system_shutdown() (see it for the whole shutdown sequence). The isolate argument -XX:TearDownWarningSeconds=<seconds> prints the stack traces of the threads that block the tear-down.

Parameters
[in]threadThe isolate thread of the current thread.
Returns
0 on success, a non-zero value on failure.