Dex.Future¶

Subclasses:: Dex.AsyncPair, Dex.Block, Dex.Cancellable, Dex.Delayed, Dex.Fiber, Dex.FutureSet, Dex.Promise, Dex.StaticFuture, Dex.Timeout, Dex.UnixSignal

Methods¶

Inherited:: Dex.Object (2)

class	`all` (futures)
class	`all_race` (futures)
class	`any` (futures)
class	`catch` (future, callback, *callback_data)
class	`catch_loop` (future, callback, *callback_data)
class	`finally_` (future, callback, *callback_data)
class	`finally_loop` (future, callback, *callback_data)
class	`first` (futures)
class	`new_for_boolean` (v_bool)
class	`new_for_double` (v_double)
class	`new_for_errno` (errno_)
class	`new_for_error` (error)
class	`new_for_fd` (fd)
class	`new_for_float` (v_float)
class	`new_for_int` (v_int)
class	`new_for_int64` (v_int64)
class	`new_for_object` (value)
class	`new_for_pointer` (pointer)
class	`new_for_string` (string)
class	`new_for_uint` (v_uint)
class	`new_for_uint64` (v_uint64)
class	`new_for_value` (value)
class	`new_infinite` ()
class	`new_take_object` (value)
class	`new_take_string` (string)
class	`then` (future, callback, *callback_data)
class	`then_loop` (future, callback, *callback_data)
	`await_` ()
	`await_boolean` ()
	`await_boxed` ()
	`await_double` ()
	`await_enum` ()
	`await_fd` ()
	`await_flags` ()
	`await_float` ()
	`await_int` ()
	`await_int64` ()
	`await_object` ()
	`await_pointer` ()
	`await_string` ()
	`await_uint` ()
	`await_uint64` ()
	`await_variant` ()
	`disown` ()
	`get_name` ()
	`get_status` ()
	`get_value` ()
	`is_pending` ()
	`is_rejected` ()
	`is_resolved` ()

Virtual Methods¶

None

Fields¶

None

Class Details¶

class Dex.Future¶

Bases:: Dex.Object
Abstract:: No

Dex.Future is the base class representing a future which may resolve with a value or reject with error at some point in the future.

It is the basis for libdex’s concurrency and parallelism model.

Use futures to represent work in progress and allow consumers to build robust processing chains up front which will complete or fail as futures resolve or reject.

When running on a Dex.Fiber, you may use Dex.Future.await_() and similar functions to suspend the current thread and return upon completion of the dependent future.

classmethod all(futures)¶

Parameters:: futures ([Dex.Future]) – an array of futures
Returns:: a Dex.Future
Return type:: Dex.Future

Creates a new Dex.Future that resolves when all futures resolve.

The resulting Dex.Future will not resolve or reject until all futures have either resolved or rejected.

classmethod all_race(futures)¶

Parameters:: futures ([Dex.Future]) – an array of futures
Returns:: a Dex.Future
Return type:: Dex.Future

Creates a new Dex.Future that resolves when all futures resolve.

If any future rejects, the resulting Dex.Future also rejects immediately.

classmethod any(futures)¶

Parameters:: futures ([Dex.Future]) – an array of futures
Returns:: a Dex.Future
Return type:: Dex.Future

Creates a new Dex.Future that resolves when the first future resolves.

If all futures reject, then the Dex.Future returned will also reject.

classmethod catch(future, callback, *callback_data)¶

Parameters:

future (Dex.Future) – a Dex.Future
callback (Dex.FutureCallback) – a callback to execute
callback_data (object or None) – closure data for callback

Returns:

a Dex.Future

Return type:

Dex.Future

Calls callback when future rejects.

If future resolves, then callback will not be called.

classmethod catch_loop(future, callback, *callback_data)¶

Parameters:

future (Dex.Future) – a Dex.Future
callback (Dex.FutureCallback) – a callback to execute
callback_data (object or None) – closure data for callback

Returns:

a Dex.Future

Return type:

Dex.Future

Asynchronously calls callback when future rejects.

This is similar to Dex.Future.catch() except that it will call callback multiple times as each returned Dex.Future rejects, allowing for infinite loops.

classmethod finally_(future, callback, *callback_data)¶

Parameters:

future (Dex.Future) – a Dex.Future
callback (Dex.FutureCallback) – a callback to execute
callback_data (object or None) – closure data for callback

Returns:

a Dex.Future

Return type:

Dex.Future

Calls callback when future resolves or rejects.

classmethod finally_loop(future, callback, *callback_data)¶

Parameters:

future (Dex.Future) – a Dex.Future
callback (Dex.FutureCallback) – a callback to execute
callback_data (object or None) – closure data for callback

Returns:

a Dex.Future

Return type:

Dex.Future

Asynchronously calls callback when future rejects or resolves.

This is similar to Dex.Future.finally_() except that it will call callback multiple times as each returned Dex.Future rejects or resolves, allowing for infinite loops.

classmethod first(futures)¶

Parameters:: futures ([Dex.Future]) – an array of futures
Returns:: a Dex.Future
Return type:: Dex.Future

Creates a new Dex.Future that resolves or rejects as soon as the first dependent future resolves or rejects, sharing the same result.

classmethod new_for_boolean(v_bool)¶

Parameters:: v_bool (bool) – the resolved value for the future
Returns:: a resolved Dex.Future
Return type:: Dex.Future

Creates a new Dex.Future and resolves it with v_bool.

classmethod new_for_double(v_double)¶

Parameters:: v_double (float) – the resolved value for the future
Returns:: a resolved Dex.Future
Return type:: Dex.Future

Creates a new Dex.Future and resolves it with v_double.

classmethod new_for_errno(errno_)¶

Parameters:: errno (int) – the errno to use for rejection
Returns:: a rejected Dex.Future.
Return type:: Dex.Future

Creates a new rejected future using errno_ as the value of errno for the GLib.Error.

The resulting error domain will be %G_IO_ERROR.

New in version 0.4.

classmethod new_for_error(error)¶

Parameters:: error (GLib.Error) – a GLib.Error
Returns:: a Dex.Future
Return type:: Dex.Future

Creates a read-only Dex.Future that has rejected.

classmethod new_for_fd(fd)¶

Parameters:: fd (int) – the file-descriptor to take ownership of
Returns:: a resolved Dex.Future
Return type:: Dex.Future

Creates a new future that resolves to fd.

This function takes ownership of fd.

classmethod new_for_float(v_float)¶

Parameters:: v_float (float) – the resolved value for the future
Returns:: a resolved Dex.Future
Return type:: Dex.Future

Creates a new Dex.Future and resolves it with v_float.

classmethod new_for_int(v_int)¶

Parameters:: v_int (int) – the resolved value for the future
Returns:: a resolved Dex.Future
Return type:: Dex.Future

Creates a new Dex.Future and resolves it with v_int.

classmethod new_for_int64(v_int64)¶

Parameters:: v_int64 (int) – the resolved value for the future
Returns:: a resolved Dex.Future
Return type:: Dex.Future

Creates a new Dex.Future and resolves it with v_int64.

classmethod new_for_object(value)¶

Parameters:: value (GObject.Object) – the value
Returns:: a resolved Dex.Future
Return type:: Dex.Future

Creates a new Dex.Future that is resolved with value.

classmethod new_for_pointer(pointer)¶

Parameters:: pointer (object or None) – the resolved future value as a pointer
Returns:: a resolved Dex.Future
Return type:: Dex.Future

Creates a new Dex.Future that is resolved with pointer as a GObject.TYPE_POINTER.

classmethod new_for_string(string)¶

Parameters:: string (str) – the resolved value for the future
Returns:: a resolved Dex.Future
Return type:: Dex.Future

Creates a new Dex.Future and resolves it with string.

classmethod new_for_uint(v_uint)¶

Parameters:: v_uint (int) – the resolved value for the future
Returns:: a resolved Dex.Future
Return type:: Dex.Future

Creates a new Dex.Future and resolves it with v_uint.

classmethod new_for_uint64(v_uint64)¶

Parameters:: v_uint64 (int) – the resolved value for the future
Returns:: a resolved Dex.Future
Return type:: Dex.Future

Creates a new Dex.Future and resolves it with v_uint64.

classmethod new_for_value(value)¶

Parameters:: value (GObject.Value) – the resolved GObject.Value
Returns:: a Dex.Future
Return type:: Dex.Future

Creates a read-only Dex.Future that has resolved.

classmethod new_infinite()¶

Returns:: a Dex.Future that will never complete or reject
Return type:: Dex.Future

Creates an infinite future that will never resolve or reject. This can be useful when you want to mock a situation of “run forever” unless another future rejects or resolves.

New in version 0.4.

classmethod new_take_object(value)¶

Parameters:: value (GObject.Object or None) – the value
Returns:: a resolved Dex.Future
Return type:: Dex.Future

Creates a new Dex.Future that is resolved with value.

classmethod new_take_string(string)¶

Parameters:: string (str) – the resolved value for the future
Returns:: a resolved Dex.Future
Return type:: Dex.Future

Creates a new Dex.Future and resolves it with string.

classmethod then(future, callback, *callback_data)¶

Parameters:

future (Dex.Future) – a Dex.Future
callback (Dex.FutureCallback) – a callback to execute
callback_data (object or None) – closure data for callback

Returns:

a Dex.Future

Return type:

Dex.Future

Calls callback when future resolves.

If future rejects, then callback will not be called.

classmethod then_loop(future, callback, *callback_data)¶

Parameters:

future (Dex.Future) – a Dex.Future
callback (Dex.FutureCallback) – a callback to execute
callback_data (object or None) – closure data for callback

Returns:

a Dex.Future

Return type:

Dex.Future

Asynchronously calls callback when future resolves.

This is similar to Dex.Future.then() except that it will call callback multiple times as each returned Dex.Future resolves or rejects, allowing for infinite loops.

await_()¶

Raises:: GLib.Error
Returns:: True if the future resolved, otherwise False and error is set.
Return type:: bool

Suspends the current Dex.Fiber and resumes when self has completed.

If self is completed when this function is called, the fiber will handle the result immediately.

This function may only be called within a Dex.Fiber. To do otherwise will return False and error set to Dex.Error.NO_FIBER.

It is an error to call this function in a way that would cause intermediate code to become invalid when resuming the stack. For example, if a foreach-style function taking a callback was to suspend from the callback, undefined behavior may occur such as thread-local-storage having changed.

await_boolean()¶

Raises:: GLib.Error
Returns:: the bool, or False and error is set
Return type:: bool

Awaits on self and returns the bool result.

If the result is not a bool, error is set.

await_boxed()¶

Raises:: GLib.Error
Returns:: the boxed result, or None and error is set.
Return type:: object or None

Awaits on self and returns the GObject.TYPE_BOXED based result.

await_double()¶

Raises:: GLib.Error
Returns:: an double, or 0 in case of failure and error is set.
Return type:: float

Awaits on self and returns the result as an double.

The resolved value must be of type GObject.TYPE_DOUBLE or error is set.

await_enum()¶

Raises:: GLib.Error
Returns:: the enum or 0 and error is set.
Return type:: int

Awaits on self and returns the enum result.

If the result is not a GObject.TYPE_ENUM, error is set.

await_fd()¶

Raises:: GLib.Error
Returns:: a valid file descriptor or -1. you may get -1 without error being set if there was no rejected future.
Return type:: int

Awaits on self and returns the resultint file-descriptor.

The resolved value must be of type %DEX_TYPE_FD or error is set.

await_flags()¶

Raises:: GLib.Error
Returns:: the flags or 0 and error is set.
Return type:: int

Awaits on self and returns the flags result.

If the result is not a GObject.TYPE_FLAGS, error is set.

await_float()¶

Raises:: GLib.Error
Returns:: an float, or 0 in case of failure and error is set.
Return type:: float

Awaits on self and returns the result as an float.

The resolved value must be of type GObject.TYPE_FLOAT or error is set.

await_int()¶

Raises:: GLib.Error
Returns:: an int, or 0 in case of failure and error is set.
Return type:: int

Awaits on self and returns the result as an int.

The resolved value must be of type GObject.TYPE_INT or error is set.

await_int64()¶

Raises:: GLib.Error
Returns:: an int64, or 0 in case of failure and error is set.
Return type:: int

Awaits on self and returns the result as an int64.

The resolved value must be of type GObject.TYPE_INT64 or error is set.

await_object()¶

Raises:: GLib.Error
Returns:: the object, or None and error is set.
Return type:: GObject.Object

Awaits on self and returns the GObject.Object-based result.

await_pointer()¶

Raises:: GLib.Error
Returns:: a pointer or None
Return type:: object or None

Calls Dex.Future.await_() and returns the value of GObject.Value.get_pointer(), otherwise error is set if the future rejected.

await_string()¶

Raises:: GLib.Error
Returns:: the string or None and error is set
Return type:: str or None

Awaits on self and returns the string result.

If the result is not a GObject.TYPE_STRING, error is set.

await_uint()¶

Raises:: GLib.Error
Returns:: an uint, or 0 in case of failure and error is set.
Return type:: int

Awaits on self and returns the result as an uint.

The resolved value must be of type GObject.TYPE_UINT or error is set.

await_uint64()¶

Raises:: GLib.Error
Returns:: an uint64, or 0 in case of failure and error is set.
Return type:: int

Awaits on self and returns the result as an uint64.

The resolved value must be of type GObject.TYPE_UINT64 or error is set.

await_variant()¶

Raises:: GLib.Error
Returns:: the variant result, or None and error is set.
Return type:: GLib.Variant

Awaits on self and returns the GObject.TYPE_VARIANT based result.

New in version 0.4.

disown()¶: Disowns a future, allowing it to run to completion even though there may be no observer interested in the futures completion or rejection.

New in version 0.4.

get_name()¶

Return type:: str

get_status()¶

Return type:: Dex.FutureStatus

get_value()¶

Raises:: GLib.Error
Return type:: GObject.Value

is_pending()¶

Returns:: True if the future is still pending; otherwise False
Return type:: bool

This is a convenience function equivalent to calling Dex.Future.get_status() and checking for Dex.FutureStatus.PENDING.

is_rejected()¶

Returns:: True if the future was rejected with an error; otherwise False
Return type:: bool

This is a convenience function equivalent to calling Dex.Future.get_status() and checking for Dex.FutureStatus.REJECTED.

is_resolved()¶

Returns:: True if the future has successfully resolved with a value; otherwise False
Return type:: bool

This is a convenience function equivalent to calling Dex.Future.get_status() and checking for Dex.FutureStatus.RESOLVED.