#include <legion.h>

Inheritance diagram for Legion::Future:

Public Member Functions
	Future (const Future &f)

	Future (Future &&f) noexcept

bool	exists (void) const

bool	operator== (const Future &f) const

bool	operator< (const Future &f) const

Future &	operator= (const Future &f)

Future &	operator= (Future &&f) noexcept

std::size_t	hash (void) const

template<typename T >
T	get_result (bool silence_warnings=false, const char *warning_string=NULL) const

void	get_void_result (bool silence_warnings=false, const char *warning_string=NULL) const

bool	is_empty (bool block=false, bool silence_warnings=false, const char *warning_string=NULL) const

bool	is_ready (bool subscribe=false) const

template<typename T , PrivilegeMode PM = LEGION_READ_ONLY>
Span< T, PM >	get_span (Memory::Kind memory, bool silence_warnings=false, const char *warning_string=NULL) const

const void *	get_buffer (Memory::Kind memory, size_t extent_in_bytes=NULL, bool check_extent=false, bool silence_warnings=false, const char warning_string=NULL) const

void	get_memories (std::set< Memory > &memories, bool silence_warnings=false, const char *warning_string=NULL) const

template<typename T >
const T &	get_reference (bool silence_warnings=false, const char *warning_string=NULL) const

const void *	get_untyped_pointer (bool silence_warnings=false, const char *warning_string=NULL) const

size_t	get_untyped_size (void) const

const void *	get_metadata (size_t *size=NULL) const

template<typename T >
T	get (void)

bool	valid (void) const

void	wait (void) const

Public Member Functions inherited from Legion::Unserializable< Future >
size_t	legion_buffer_size (void)

size_t	legion_serialize (void *buffer)

size_t	legion_deserialize (const void *buffer)

Static Public Member Functions
template<typename T >
static Future	from_value (Runtime *rt, const T &value)

template<typename T >
static Future	from_value (const T &value)

static Future	from_untyped_pointer (Runtime rt, const void buffer, size_t bytes, bool take_ownership=false)

static Future	from_untyped_pointer (const void buffer, size_t bytes, bool take_ownership=false, const char provenance=NULL, bool shard_local=false)

static Future	from_value (const void buffer, size_t bytes, bool owned, const Realm::ExternalInstanceResource &resource, void(freefunc)(const Realm::ExternalInstanceResource &)=NULL, const char *provenance=NULL, bool shard_local=false)

Protected Member Functions
FRIEND_ALL_RUNTIME_CLASSES	Future (Internal::FutureImpl *impl)

Detailed Description

Futures are the objects returned from asynchronous task launches. Applications can wait on futures to get their values, pass futures as arguments and preconditions to other tasks, or use them to create predicates if they are boolean futures. Futures are lightweight handles that can be passed by value or stored in data structures. However, futures should not escape the context in which they are created as the runtime garbage collects them after the enclosing task context completes execution.

Since futures can be the result of predicated tasks we also provide a mechanism for checking whether the future contains an empty result. An empty future will be returned for all futures which come from tasks which predicates that resolve to false.

Member Function Documentation

◆ from_untyped_pointer()

static Future Legion::Future::from_untyped_pointer	(	Runtime *	rt,
		const void *	buffer,
		size_t	bytes,
		bool	take_ownership = `false`
	)

static

Generates a future from an untyped pointer. No serialization is performed.

◆ from_value()

template<typename T >

static Future Legion::Future::from_value	(	Runtime *	rt,
		const T &	value
	)

inlinestatic

Allow users to generate their own futures. These futures are guaranteed to always have completed and to always have concrete values.

◆ get_buffer()

const void* Legion::Future::get_buffer	(	Memory::Kind	memory,
		size_t *	extent_in_bytes = `NULL`,
		bool	check_extent = `false`,
		bool	silence_warnings = `false`,
		const char *	warning_string = `NULL`
	)		const

Return a pointer and optional size for the data for the future. The pointer is only valid as long as the application program maintains a handle to the future object that produced it. This call will not deserialized data packed with the legion_serialize method.

Parameters

memory	the kind of memory for the allocation, the memory with the best affinity to the executing processor will be used
extent_in_bytes	pointer to a location to write the future size
check_extent	check that the extent matches the future size
silence_warnings	silence any warnings for this blocking call
warning_string	a string to be reported with any warnings

Returns: a const pointer to the future data in the specified memory

◆ get_memories()

void Legion::Future::get_memories	(	std::set< Memory > &	memories,
		bool	silence_warnings = `false`,
		const char *	warning_string = `NULL`
	)		const

Report an instantaneous set of available memories where instances for the this future exist. These will only be memories local to the current process in which the call is performed. The result of this query might be come stale as soon as it is returned since it is only a snapshot of the memories where the future has copies.

◆ get_metadata()

const void* Legion::Future::get_metadata ( size_t * size = NULL ) const

Return a pointer to the metadata buffer for this future. Unlike getting a buffer for the future which can exist on any memory, the metadata is always guaranteed to be on the host memory.

Parameters

optional pointer to a place to write the size

Returns: a pointer to the buffer containing the metadata

◆ get_reference()

template<typename T >

const T& Legion::Future::get_reference	(	bool	silence_warnings = `false`,
		const char *	warning_string = `NULL`
	)		const

inline

Return a const reference to the future. WARNING: these method is unsafe as the underlying buffer containing the future result can be deleted if the Future handle is lost even a reference to the underlying buffer is maitained. This scenario can lead to seg-faults. Use at your own risk. Note also that this call will not properly deserialize buffers that were serialized with a 'legion_serialize' method.

Parameters

silence_warnings	silence any warnings for this blocking call
warning_string	a string to be reported with the warning

◆ get_result()

template<typename T >

T Legion::Future::get_result	(	bool	silence_warnings = `false`,
		const char *	warning_string = `NULL`
	)		const

inline

Wait on the result of this future. Return the value of the future as the specified template type.

Parameters

silence_warnings	silence any warnings for this blocking call
warning_string	a string to be reported with the warning

Returns: the value of the future cast as the template type

◆ get_span()

template<typename T , PrivilegeMode PM = LEGION_READ_ONLY>

Span<T,PM> Legion::Future::get_span	(	Memory::Kind	memory,
		bool	silence_warnings = `false`,
		const char *	warning_string = `NULL`
	)		const

Return a span object representing the data for the future. The size of the future must be evenly divisible by sizeof(T). The resulting span object is only good as long as the application program maintains a handle to the future object that created it. At the moment the privilege mode must be read-only; no other values will be accepted. This call will not unpack data serialized with the legion_serialize method.

Parameters

memory	the kind of memory for the allocation, the memory with the best affinity to the executing processor will be used
silence_warnings	silence any warnings for this blocking call
warning_string	a string to be reported with any warnings

Returns: a Span object representing the data for the future

◆ get_untyped_pointer()

const void* Legion::Future::get_untyped_pointer	(	bool	silence_warnings = `false`,
		const char *	warning_string = `NULL`
	)		const

inline

Return an untyped pointer to the future result. WARNING: this method is unsafe for the same reasons as get_reference. It also will not deserialize anything serialized with a legion_serialize method.

Parameters

silence_warnings	silence any warnings for this blocking call
warning_string	a string to be reported with the warning

◆ get_untyped_size()

size_t Legion::Future::get_untyped_size ( void ) const

Return the number of bytes contained in the future.

◆ get_void_result()

void Legion::Future::get_void_result	(	bool	silence_warnings = `false`,
		const char *	warning_string = `NULL`
	)		const

Block until the future completes.

Parameters

silence_warnings	silence any warnings for this blocking call
warning_string	a string to be reported with the warning

◆ is_empty()

bool Legion::Future::is_empty	(	bool	block = `false`,
		bool	silence_warnings = `false`,
		const char *	warning_string = `NULL`
	)		const

Check to see if the future is empty. The user can specify whether to block and wait for the future to complete first before returning. If the non-blocking version of the call will return true, until the future actually completes.

Parameters

block	indicate whether to block for the result
silence_warnings	silence any warnings for this blocking call
warning_string	a string to be reported with the warning

◆ is_ready()

bool Legion::Future::is_ready ( bool subscribe = false ) const

Check to see if the future is ready. This will return true if the future can be used without blocking to wait on the computation that the future represents, otherwise it will return false.

Parameters

subscribe ask for the payload to be brought here when ready

The documentation for this class was generated from the following file:

legion.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation

◆ from_untyped_pointer()

◆ from_value()

◆ get_buffer()

◆ get_memories()

◆ get_metadata()

◆ get_reference()

◆ get_result()

◆ get_span()

◆ get_untyped_pointer()

◆ get_untyped_size()

◆ get_void_result()

◆ is_empty()

◆ is_ready()