### Namespace

# Dex – 1

A GNOME library for deferred execution

Version | 1.2.beta
Authors | Christian Hergert
License | LGPL-2.1-or-later
Website | https://gitlab.gnome.org/GNOME/libdex/
Source | https://gitlab.gnome.org/GNOME/libdex/

#### Build

C headers | `libdex.h`
pkg-config files | `libdex-1`

#### Dependencies

GLib—2.0 | The base type system library
| Browse documentation
GObject—2.0 | The base type system library
| Browse documentation
GioUnix—2.0 | GIO UNIX-specific APIs
| Browse documentation

#### Additional documentation

- Overview
- Terminology
- Integrating GAsyncResult
- Asynchronous IO
- Schedulers & Fibers
- Stackless Coroutines
- Threads for Blocking APIs
- Channels
- Limiters
- State Machines
- D-Bus
- Debugging
- Classes Hierarchy

#### Classes

AsyncPair |
AsyncResult | `DexAsyncResult` is used to integrate a `DexFuture` with `GAsyncResult`.
Block | `DexBlock` represents a callback closure that can be scheduled to run within a specific `GMainContext`.
Cancellable | `DexCancellable` is a simple cancellation primitive which allows for you to create `DexFuture` that will reject upon cancellation.
Channel |
Coroutine | `DexCoroutine` is a `DexFuture` implemented as a stateful stackless coroutine cooperatively scheduled on a `DexScheduler`.
Delayed | `DexDelayed` is a future which will resolve or reject the value of another `DexFuture` when `dex_delayed_release()` is called.
Fiber | `DexFiber` is a fiber (a stack-based coroutine) which itself is a `DexFuture`.
Future | `DexFuture` is the base class representing a future which may resolve with a value or reject with error at some point in the future.
FutureListModel | This class provides a `GListModel` implementation that will expand to the contents of another `GListModel` from a `DexFuture`. since: 1.1
FutureSet | `DexFutureSet` represents a set of `DexFuture`.
Limiter | `DexLimiter` limits the number of operations running concurrently. unstable since: 1.2
MainScheduler | `DexMainScheduler` is the scheduler used on the default thread of an application. It is meant to integrate with your main loop.
Object | `DexObject` is the basic building block of types defined within libdex. Futures, Schedulers, and Channels all inherit from `DexObject` which provides features like thread-safe weak pointers and memory management operations.
Promise | `DexPromise` is a convenient `DexFuture` for propagating a result or rejection in application and library code.
Scheduler | `DexScheduler` is the base class used by schedulers.
StateMachine | `DexStateMachine` provides a serialized asynchronous state machine.
StaticFuture | `DexStaticFuture` represents a future that is resolved from the initial state.
TaskGroup | A structured scope for related `DexFuture` instances. unstable since: 1.2
ThreadPool | `DexThreadPool` is a thread pool for managing native OS threads similar to `GThreadPool`. unstable since: 1.2
ThreadPoolScheduler | `DexThreadPoolScheduler` is a `DexScheduler` that will dispatch work items and fibers to sub-schedulers on a specific operating system thread.
Timeout | `DexTimeout` is a `DexFuture` that will reject after the configured period of time.
UnixSignal | `DexUnixSignal` is a `DexFuture` that will resolve when a specific unix signal has been received.

#### Structs

AioContext |
AsyncPairInfo |
CoroutineContext |
StateTransition | Describes one supported transition edge in a `DexStateMachine`.
StateTransitionContext | `DexStateTransitionContext` is an opaque per-callback structure with information and state access for a `DexStateTransition` callback. unstable since: 1.2

#### Enumerations

BlockKind |
FutureStatus |
ThreadPoolShutdownMode |

#### Bitfields

TaskGroupFlags |

#### Error Domains

Error |

#### Callbacks

CoroutineFunc | This function prototype is used for spawning stackless coroutines.
FiberFunc | This function prototype is used for spawning fibers. A fiber is a lightweight, cooperative-multitasking feature where the fiber is given its own stack. The fiber runs until it reaches a point of suspension (using `dex_await()` or similar) or exits the fiber.
FutureCallback | A `DexFutureCallback` can be executed from a `DexBlock` as response to another `DexFuture` resolving or rejecting.
SchedulerFunc |
StateTransitionFunc | Callback used to execute a transition edge.
ThreadFunc | A function which will be run on a dedicated thread. since: 1.0

#### Functions

aio_close | An asynchronous `close()` wrapper. unstable since: 1.2
aio_open | An asynchronous `open()` wrapper. unstable since: 1.2
aio_read | An asynchronous `pread()` wrapper.
aio_write | An asynchronous `pwrite()` wrapper.
app_info_get_default_for_type | Wraps `g_app_info_get_default_for_type_async()`. unstable since: 1.2
app_info_get_default_for_uri_scheme | Wraps `g_app_info_get_default_for_uri_scheme_async()`. unstable since: 1.2
app_info_launch_default_for_uri | Wraps `g_app_info_launch_default_for_uri_async()`. unstable since: 1.2
app_info_launch_uris | Wraps `g_app_info_launch_uris_async()`. unstable since: 1.2
async_initable_init | A helper for `g_async_initable_init_async()`. since: 1.0
async_initable_new | Creates and asynchronously initializes a new object. unstable since: 1.2
buffered_input_stream_fill | Wraps `g_buffered_input_stream_fill_async()`. unstable since: 1.2
bus_get | Wrapper for `g_bus_get()`. since: 0.4
bus_own_name_on_connection | Wrapper for `g_bus_own_name()`. since: 1.1
data_input_stream_read_line | Reads a line from the data input stream. since: 1.1
data_input_stream_read_line_utf8 | Reads a UTF-8 line from the data input stream. unstable since: 1.2
data_input_stream_read_upto | Reads data from the stream until one of `stop_chars` is found. unstable since: 1.2
dbus_connection_call | Wrapper for `g_dbus_connection_call()`. since: 0.4
dbus_connection_call_with_unix_fd_list | Wrapper for `g_dbus_connection_call_with_unix_fd_list()`. since: 0.4
dbus_connection_close | Asynchronously closes a connection. since: 1.0
dbus_connection_send_message_with_reply | Wrapper for `g_dbus_connection_send_message_with_reply()`. since: 0.4
dtls_connection_close | Wraps `g_dtls_connection_close_async()`. unstable since: 1.2
dtls_connection_handshake | Wraps `g_dtls_connection_handshake_async()`. unstable since: 1.2
dtls_connection_shutdown | Wraps `g_dtls_connection_shutdown_async()`. unstable since: 1.2
error_quark |
fd_watch | Creates a new GSource that will fire when `events` is satisfied. since: 1.1
file_append_to | Wraps `g_file_append_to_async()` as a `DexFuture`. unstable since: 1.2
file_copy | Asynchronously copies a file and returns a `DexFuture` which can be observed for the result.
file_copy_with_progress | Wraps `g_file_copy_async()` with progress callback support. unstable since: 1.2
file_create | Wraps `g_file_create()` as a `DexFuture`. since: 1.1
file_create_readwrite | Wraps `g_file_create_readwrite_async()` as a `DexFuture`. unstable since: 1.2
file_delete | Asynchronously deletes a file and returns a `DexFuture` which can be observed for the result.
file_enumerate_children |
file_enumerator_close | Wraps `g_file_enumerator_close_async()`. unstable since: 1.2
file_enumerator_next_files | Wraps `g_file_enumerator_next_files_async()`.
file_find_enclosing_mount | Wraps `g_file_find_enclosing_mount_async()`. unstable since: 1.2
file_input_stream_query_info | Wraps `g_file_input_stream_query_info_async()`. unstable since: 1.2
file_io_stream_query_info | Wraps `g_file_io_stream_query_info_async()`. unstable since: 1.2
file_load_bytes | Wraps `g_file_load_bytes_async()`. unstable since: 1.2
file_load_contents_bytes |
file_load_partial_contents_bytes | Wraps `g_file_load_partial_contents_async()`. unstable since: 1.2
file_make_directory | Asynchronously creates a directory and returns `DexFuture` which can be observed for the result.
file_make_directory_with_parents | Creates a directory at `file`. since: 1.0
file_make_symbolic_link | Wraps `g_file_make_symbolic_link_async()`. unstable since: 1.2
file_move |
file_new_tmp_dir | Wraps `g_file_new_tmp_dir_async()` as a `DexFuture`. unstable since: 1.2
file_open_readwrite | Wraps `g_file_open_readwrite_async()` as a `DexFuture`. unstable since: 1.2
file_output_stream_query_info | Wraps `g_file_output_stream_query_info_async()`. unstable since: 1.2
file_query_default_handler | Wraps `g_file_query_default_handler_async()`. unstable since: 1.2
file_query_exists | Queries to see if `file` exists asynchronously. since: 0.6
file_query_file_type |
file_query_filesystem_info | Wraps `g_file_query_filesystem_info_async()`. unstable since: 1.2
file_query_info |
file_read | Asynchronously opens a file for reading.
file_replace | Opens a stream that will replace `file` on disk when the input stream is closed.
file_replace_contents | Wraps `g_file_replace_contents_async()`. unstable since: 1.2
file_replace_contents_bytes | Wraps `g_file_replace_contents_bytes_async()`.
file_replace_readwrite | Wraps `g_file_replace_readwrite_async()` as a `DexFuture`. unstable since: 1.2
file_set_attributes | since: 1.0
file_set_display_name | Wraps `g_file_set_display_name_async()`. unstable since: 1.2
file_trash | Wraps `g_file_trash_async()`. unstable since: 1.2
find_program_in_path | Locates the first executable named program in the user’s path. since: 1.1
get_major_version | Gets the major version number equivalent to `DEX_MAJOR_VERSION` at compile time of libdex. since: 1.1
get_micro_version | Gets the micro version number equivalent to `DEX_MICRO_VERSION` at compile time of libdex. since: 1.1
get_min_stack_size |
get_minor_version | Gets the minor version number equivalent to `DEX_MINOR_VERSION` at compile time of libdex. since: 1.1
get_page_size |
init |
input_stream_close |
input_stream_read | Reads `count` bytes from an input stream into a pre-allocated `buffer`. The `buffer` must stay valid for the lifetime of this future.
input_stream_read_bytes | Reads `count` bytes from the stream.
input_stream_skip |
io_stream_close |
io_stream_splice | Wraps `g_io_stream_splice_async()`. unstable since: 1.2
mkdir_with_parents | Similar to `g_mkdir_with_parents()` but runs on a dedicated thread. since: 1.1
network_monitor_can_reach | Wraps `g_network_monitor_can_reach_async()`. unstable since: 1.2
output_stream_close |
output_stream_flush | Wraps `g_output_stream_flush_async()`. unstable since: 1.2
output_stream_splice |
output_stream_write |
output_stream_write_bytes | Writes `bytes` to `stream`.
output_stream_writev_all | Writes all bytes in `vectors` to `stream`. unstable since: 1.2
param_spec_object | Creates a new `GParamSpec` instance specifying a `DEX_TYPE_OBJECT` derived property. unstable since: 1.2
permission_acquire | Wraps `g_permission_acquire_async()`. unstable since: 1.2
permission_release | Wraps `g_permission_release_async()`. unstable since: 1.2
proxy_connect | Wraps `g_proxy_connect_async()`. unstable since: 1.2
proxy_resolver_lookup | Wraps `g_proxy_resolver_lookup_async()`. unstable since: 1.2
resolver_lookup_by_address | Wraps `g_resolver_lookup_by_address_async()`. unstable since: 1.2
resolver_lookup_by_name |
resolver_lookup_by_name_with_flags | Wraps `g_resolver_lookup_by_name_with_flags_async()`. unstable since: 1.2
resolver_lookup_records | Wraps `g_resolver_lookup_records_async()`. unstable since: 1.2
resolver_lookup_service | Wraps `g_resolver_lookup_service_async()`. unstable since: 1.2
socket_address_enumerator_next | Wraps `g_socket_address_enumerator_next_async()`. unstable since: 1.2
socket_client_connect |
socket_client_connect_to_host | Wraps `g_socket_client_connect_to_host_async()`. unstable since: 1.2
socket_client_connect_to_service | Wraps `g_socket_client_connect_to_service_async()`. unstable since: 1.2
socket_client_connect_to_uri | Wraps `g_socket_client_connect_to_uri_async()`. unstable since: 1.2
socket_connection_connect | Wraps `g_socket_connection_connect_async()`. unstable since: 1.2
socket_listener_accept |
socket_wait | Creates a `DexFuture` that resolves when `socket` satisfies `condition`. unstable since: 1.2
subprocess_wait | Wraps `g_subprocess_wait_async()`. unstable since: 1.2
subprocess_wait_check | Creates a future that awaits for `subprocess` to complete using `g_subprocess_wait_check_async()`. since: 0.4
test_add_func | Adds a test function like g_test_add_func(), but runs `test_func` from a `DexFiber`. The calling thread is given a thread-default `DexScheduler` if it does not already have one, allowing tests to use `dex_await()` and related APIs directly.
thread_spawn | Spawns a new thread named `thread_name` running `thread_func` with `user_data` passed to it. since: 1.0
thread_wait_for | Use this when running on a thread spawned with `dex_thread_spawn()` and you need to block the thread until `future` has resolved or rejected. since: 1.0
tls_connection_handshake | unstable since: 1.2
tls_database_lookup_certificate_for_handle | Wraps `g_tls_database_lookup_certificate_for_handle_async()`. unstable since: 1.2
tls_database_lookup_certificate_issuer | Wraps `g_tls_database_lookup_certificate_issuer_async()`. unstable since: 1.2
tls_database_lookup_certificates_issued_by | Wraps `g_tls_database_lookup_certificates_issued_by_async()`. unstable since: 1.2
tls_database_verify_chain | Wraps `g_tls_database_verify_chain_async()`. unstable since: 1.2
tls_interaction_ask_password | Wraps `g_tls_interaction_ask_password_async()`. unstable since: 1.2
tls_interaction_request_certificate | Wraps `g_tls_interaction_request_certificate_async()`. unstable since: 1.2
unix_connection_receive_credentials | Wraps `g_unix_connection_receive_credentials_async()`. unstable since: 1.2
unix_connection_send_credentials | Wraps `g_unix_connection_send_credentials_async()`. unstable since: 1.2
unlink | This runs `g_unlink()` on a dedicated thread. since: 1.1
value_dup_object | Retrieves the `DexObject` stored inside the given `value`. since: 1.0
value_get_object | Retrieves the `DexObject` stored inside the given `value`. since: 0.4
value_set_object | Stores the given `DexObject` inside `value`. since: 0.4
value_take_object | Stores the given `DexObject` inside `value`. since: 0.4

#### Function Macros

ASYNC_PAIR_INFO_BOOLEAN |
ASYNC_PAIR_INFO_BOXED |
ASYNC_PAIR_INFO_INT |
ASYNC_PAIR_INFO_INT64 |
ASYNC_PAIR_INFO_LONG |
ASYNC_PAIR_INFO_OBJECT |
ASYNC_PAIR_INFO_POINTER |
ASYNC_PAIR_INFO_STRING |
ASYNC_PAIR_INFO_UINT |
ASYNC_PAIR_INFO_UINT64 |
ASYNC_PAIR_INFO_ULONG |
COROUTINE_BEGIN | Used in a coroutine function body to establish coroutine state.
COROUTINE_SUSPEND |
COROUTINE_SUSPEND_BOOLEAN |
COROUTINE_SUSPEND_BOXED |
COROUTINE_SUSPEND_DOUBLE |
COROUTINE_SUSPEND_ENUM |
COROUTINE_SUSPEND_FLAGS |
COROUTINE_SUSPEND_FLOAT |
COROUTINE_SUSPEND_INT |
COROUTINE_SUSPEND_INT64 |
COROUTINE_SUSPEND_OBJECT |
COROUTINE_SUSPEND_POINTER |
COROUTINE_SUSPEND_UINT |
COROUTINE_SUSPEND_UINT64 |
DEFINE_CLOSURE_OBJECT | An object pointer field descriptor for #DEX_DEFINE_CLOSURE_TYPE().
DEFINE_CLOSURE_POINTER | A pointer field descriptor for #DEX_DEFINE_CLOSURE_TYPE(). `clear` is required; use #DEX_DEFINE_CLOSURE_VALUE() for pointers which do not need cleanup.
DEFINE_CLOSURE_TYPE | This macro is a lightweight helper for quickly defining closure-like state structs with matching `type_prefix_new()` and `type_prefix_free()` helpers. unstable since: 1.2
DEFINE_CLOSURE_VALUE | A value field descriptor for #DEX_DEFINE_CLOSURE_TYPE().
DEFINE_CLOSURE_VALUE_WITH_CLEAR | A value field descriptor for #DEX_DEFINE_CLOSURE_TYPE() which is cleared by calling `clear` with the address of the value.
DEPRECATED_FOR |
DEPRECATED_IN_1_0_FOR |
DEPRECATED_IN_1_1_FOR |
DEPRECATED_IN_1_2_FOR |
future_new_false |
future_new_true |
OBJECT_TYPE |
OBJECT_TYPE_NAME |
return_error_if_fail |
UNAVAILABLE |