A future is a possibly yet unevaluated value. More...

#include <future.h>

Classes
class	dddd

Public Types
typedef RemoteReference< FutureImpl< T > >	remote_refT

Public Member Functions
	Future ()
	Makes an unassigned future.

	Future (const archive::BufferInputArchive &input_arch)
	Makes an assigned future from an input archive.

	Future (const Future< T > &other)
	Shallow copy constructor.

	Future (const remote_refT &remote_ref)
	Makes a future wrapping a remote reference.

	Future (const T &t)
	Makes an assigned future.

	~Future ()
	Destructor.

T &	get (bool dowork=true) &
	Gets the value, waiting if necessary.

T	get (bool dowork=true) &&
	Gets the value, waiting if necessary.

const T &	get (bool dowork=true) const &
	Gets the value, waiting if necessary.

bool	is_default_initialized () const
	Check if the future is default initialized.

bool	is_local () const
	Checks the future remoteness trait.

bool	is_remote () const
	Checks the future remoteness trait.

	operator const T & () const &
	Same as `get() const&`.

	operator T () &&
	An rvalue analog of `get()`.

	operator T& () &
	Same as `get()&`.

Future< T > &	operator= (const Future< T > &other)
	Shallow assignment operator.

bool	probe () const
	Check whether this future has been assigned.

void	register_callback (CallbackInterface *callback)
	Registers an object to be called when future is assigned.

remote_refT	remote_ref (World &world) const
	Returns a structure used to pass references to another process.

void	set (const archive::BufferInputArchive &input_arch)
	Assigns the value.

void	set (const Future< T > &other)
	`A.set(B)`, where `A` and `B` are futures ensures `A` has/will have the same value as `B`.

void	set (const T &value)
	Assigns the value.

void	set (T &&value)
	Assigns the value.

Static Public Member Functions
static const Future< T >	default_initializer ()
	See "Gotchas" on Futures about why this exists and how to use it.

Private Member Functions
	Future (const dddd &blah)

Private Attributes
char	buffer [sizeof(T)]
	Buffer to hold a single `T` object.

std::shared_ptr< FutureImpl< T > >	f
	Pointer to the implementation object.

T *const	value
	Pointer to buffer when it holds a `T` object.

Friends
std::ostream &	operator<< (std::ostream &out, const Future< T > &f)
	Human readable printing of a `Future` to a stream.

Detailed Description

template<typename T>
class madness::Future< T >

A future is a possibly yet unevaluated value.

Uses delegation to FutureImpl to provide desired copy/assignment semantics, as well as safe reference counting for remote futures.

Since we are using futures a lot to store local values coming from containers and inside task wrappers for messages, we included in this class a value. If a future is assigned before a copy/remote-reference is taken, the shared pointer is never made. The point of this is to eliminate the two mallocs that must be peformed for every new shared_ptr.

Template Parameters

T	The type of future.

Todo:: Can this detailed description be made clearer?

Member Typedef Documentation

◆ remote_refT

template<typename T >

typedef RemoteReference< FutureImpl<T> > madness::Future< T >::remote_refT

Todo:: Brief description needed.

Constructor & Destructor Documentation

◆ Future() [1/6]

template<typename T >

madness::Future< T >::Future ( const dddd & blah )

inlineexplicitprivate

Todo:: Constructor for ...

Todo:: Description needed.

Parameters

[in] blah Description needed.

◆ Future() [2/6]

template<typename T >

madness::Future< T >::Future ( )

inline

Makes an unassigned future.

◆ Future() [3/6]

template<typename T >

madness::Future< T >::Future ( const T & t )

inlineexplicit

Makes an assigned future.

Todo:: Description needed.

Parameters

[in] t Description needed.

◆ Future() [4/6]

template<typename T >

madness::Future< T >::Future ( const remote_refT & remote_ref )

inlineexplicit

Makes a future wrapping a remote reference.

Parameters

[in] remote_ref The remote reference.

◆ Future() [5/6]

template<typename T >

madness::Future< T >::Future ( const archive::BufferInputArchive & input_arch )

inlineexplicit

Makes an assigned future from an input archive.

Parameters

[in] input_arch The input archive.

◆ Future() [6/6]

template<typename T >

madness::Future< T >::Future ( const Future< T > & other )

inline

Shallow copy constructor.

Parameters

[in] other The future to copy.

References madness::Future< T >::f, and madness::Future< T >::is_default_initialized().

◆ ~Future()

template<typename T >

madness::Future< T >::~Future ( )

inline

Destructor.

References madness::Future< T >::value.

Member Function Documentation

◆ default_initializer()

template<typename T >

static const Future< T > madness::Future< T >::default_initializer ( )

inlinestatic

See "Gotchas" on Futures about why this exists and how to use it.

Todo:: Informative description needed.

Referenced by madness::future_vector_factory(), and madness::WorldGopInterface::reduce_internal().

◆ get() [1/3]

template<typename T >

T & madness::Future< T >::get ( bool dowork = true ) &

inline

Gets the value, waiting if necessary.

Parameters

dowork If true (default) and the future is not ready this thread will execute other tasks while waiting

Warning: PaRSEC backend does not support dowork=true from a callstack containing a running MADNESS task already, hence must use dowork=false when need to call from within a task

Returns: reference to the contained value

Precondition: this->is_local()

References madness::Future< T >::f, madness::Future< T >::is_local(), MADNESS_CHECK, and madness::Future< T >::value.

Referenced by madness::WorldGopInterface::bcast_internal(), madness::WorldGopInterface::bcast_internal(), madness::Derivative< T, NDIM >::do_diff2b(), madness::MacroTaskQ::get_scheduled_task_number(), main(), madness::WorldGopInterface::DelayedSend< keyT, valueT >::notify(), madness::Future< bool >::operator bool(), madness::Future< bool >::operator bool &(), madness::Future< bool >::operator const bool &(), madness::Future< std::vector< Future< T > > >::operator const vectorT &(), madness::Future< std::vector< Future< T > > >::operator vectorT &(), madness::LoadBalanceDeux< NDIM >::print_tree(), madness::WorldGopInterface::reduce_result_task(), madness::WorldGopInterface::send_internal(), madness::Future< T >::set(), test10(), test5(), test9(), and madness::FunctionImpl< T, NDIM >::truncate_spawn().

◆ get() [2/3]

template<typename T >

T madness::Future< T >::get ( bool dowork = true ) &&

inline

Gets the value, waiting if necessary.

Parameters

dowork If true (default) and the future is not ready this thread will execute other tasks while waiting

Warning: PaRSEC backend does not support dowork=true from a callstack containing a running MADNESS task already, hence must use dowork=false when need to call from within a task

Returns: the contained value

Precondition: this->is_local()

References madness::Future< T >::f, madness::Future< T >::is_local(), MADNESS_CHECK, and madness::Future< T >::value.

◆ get() [3/3]

template<typename T >

const T & madness::Future< T >::get ( bool dowork = true ) const &

inline

Gets the value, waiting if necessary.

Parameters

dowork If true (default) and the future is not ready this thread will execute other tasks while waiting

Warning: PaRSEC backend does not support dowork=true from a callstack containing a running MADNESS task already, hence must use dowork=false when need to call from within a task

Returns: reference to the contained value

Precondition: this->is_local()

References madness::Future< T >::f, madness::Future< T >::is_local(), MADNESS_CHECK, and madness::Future< T >::value.

◆ is_default_initialized()

template<typename T >

bool madness::Future< T >::is_default_initialized ( ) const

inline

Check if the future is default initialized.

Returns: True if this future was constructed with default_initializer(); false otherwise.

References madness::Future< T >::f, and madness::Future< T >::value.

Referenced by madness::Future< T >::Future().

◆ is_local()

template<typename T >

bool madness::Future< T >::is_local ( ) const

inline

Checks the future remoteness trait.

Returns: true if the future refers to an already available or to-be-locally-produced result

References madness::Future< T >::f, and madness::Future< T >::value.

Referenced by madness::Future< T >::get(), madness::Future< T >::get(), madness::Future< T >::get(), and madness::Future< T >::is_remote().

◆ is_remote()

template<typename T >

bool madness::Future< T >::is_remote ( ) const

inline

Checks the future remoteness trait.

Returns: true if the future refers to another future on a another rank, i.e. it will be set when the referred-to future is set

References madness::Future< T >::is_local().

◆ operator const T &()

template<typename T >

madness::Future< T >::operator const T & ( ) const &

inline

Same as get() const&.

Returns: A const lvalue reference to the value.

◆ operator T()

template<typename T >

madness::Future< T >::operator T ( ) &&

inline

An rvalue analog of get().

Returns: An rvalue reference to the value.

◆ operator T&()

template<typename T >

madness::Future< T >::operator T& ( ) &

inline

Same as get()&.

Returns: An lvalue reference to the value.

◆ operator=()

template<typename T >

Future< T > & madness::Future< T >::operator= ( const Future< T > & other )

inline

Shallow assignment operator.

Parameters

[in] other The future to copy.

Returns: This.

References madness::Future< T >::f, MADNESS_ASSERT, madness::Future< T >::probe(), madness::Future< T >::set(), and madness::Future< T >::value.

◆ probe()

template<typename T >

bool madness::Future< T >::probe ( ) const

inline

Check whether this future has been assigned.

Returns: True if the future has been assigned; false otherwise.

References madness::Future< T >::f, and madness::Future< T >::value.

Referenced by madness::WorldGopInterface::bcast(), madness::WorldGopInterface::bcast(), madness::WorldGopInterface::bcast_internal(), madness::WorldGopInterface::bcast_internal(), madness::TaskFn< fnT, arg1T, arg2T, arg3T, arg4T, arg5T, arg6T, arg7T, arg8T, arg9T >::check_dependency(), madness::TaskFn< fnT, arg1T, arg2T, arg3T, arg4T, arg5T, arg6T, arg7T, arg8T, arg9T >::check_dependency(), madness::WorldGopInterface::lazy_sync_internal(), madness::WorldGopInterface::DelayedSend< keyT, valueT >::notify(), madness::Future< T >::operator=(), madness::Future< T >::register_callback(), madness::Future< T >::remote_ref(), madness::WorldGopInterface::send_internal(), madness::Future< T >::set(), and test5().

◆ register_callback()

template<typename T >

void madness::Future< T >::register_callback ( CallbackInterface * callback )

inline

Registers an object to be called when future is assigned.

Callbacks are invoked in the order registered. If the future is already assigned, the callback is immediately invoked.

Parameters

[in] callback The callback to be invoked.

References madness::Future< T >::f, MADNESS_ASSERT, madness::CallbackInterface::notify(), and madness::Future< T >::probe().

Referenced by madness::TaskFn< fnT, arg1T, arg2T, arg3T, arg4T, arg5T, arg6T, arg7T, arg8T, arg9T >::check_dependency(), and madness::TaskFn< fnT, arg1T, arg2T, arg3T, arg4T, arg5T, arg6T, arg7T, arg8T, arg9T >::check_dependency().

◆ remote_ref()

template<typename T >

remote_refT madness::Future< T >::remote_ref ( World & world ) const

inline

Returns a structure used to pass references to another process.

This is used for passing pointers/references to another process. To make remote references completely safe, the RemoteReference increments the internal reference count of the Future. The counter is decremented by either assigning to the remote Future or its destructor if it is never assigned. The remote Future is only useful for setting the future. It will not be notified if the value is set elsewhere.

If this is already a reference to a remote future, the actual remote reference is returned; that is, not a a reference to the local future. Therefore, the local future will not be notified when the result is set (i.e., the communication is short circuited).

Parameters

[in,out] world The communication world.

Todo:: Verify the return comment.

Returns: The remote reference.

References madness::Future< T >::f, MADNESS_ASSERT, and madness::Future< T >::probe().

Referenced by madness::Function< T, NDIM >::eval(), madness::Function< T, NDIM >::evaldepthpt(), madness::Function< T, NDIM >::evalR(), madness::WorldContainerImpl< keyT, valueT, hashfunT >::find(), madness::FunctionImpl< T, NDIM >::find_me(), madness::DerivativeBase< T, NDIM >::find_neighbor(), and madness::FunctionImpl< T, NDIM >::project_out2().

◆ set() [1/4]

template<typename T >

void madness::Future< T >::set ( const archive::BufferInputArchive & input_arch )

inline

Assigns the value.

The value can only be set once.

Todo:: Description needed.

Parameters

[in] input_arch Description needed.

References madness::Future< T >::f, and MADNESS_CHECK.

◆ set() [2/4]

template<typename T >

void madness::Future< T >::set ( const Future< T > & other )

inline

A.set(B), where A and B are futures ensures A has/will have the same value as B.

An exception is thrown if A is already assigned since a Future is a single assignment variable. We don't yet track multiple assignments from unassigned futures.

If B is already assigned, this is the same as A.set(B.get()), which sets A to the value of B.

If B has not yet been assigned, the behavior is to ensure that, when B is assigned, both A and B will be assigned and have the same value (though they may/may not refer to the same underlying copy of the data and indeed may even be in different processes).

Todo:: Verification needed in the param statement.

Parameters

[in] other The future B described above. *this is A.

References madness::Future< T >::f, fred(), madness::Future< T >::get(), MADNESS_ASSERT, madness::Future< T >::probe(), and madness::Future< T >::set().

◆ set() [3/4]

template<typename T >

void madness::Future< T >::set ( const T & value )

inline

Assigns the value.

The value can only be set once.

Parameters

[in] value The value to be assigned.

References madness::Future< T >::f, MADNESS_CHECK, and madness::Future< T >::value.

◆ set() [4/4]

template<typename T >

void madness::Future< T >::set ( T && value )

inline

Assigns the value.

The value can only be set once.

Parameters

[in] value The value to be assigned.

References madness::Future< T >::f, MADNESS_CHECK, and madness::Future< T >::value.

Friends And Related Symbol Documentation

◆ operator<<

template<typename T >

std::ostream & operator<<	(	std::ostream &	out,
		const Future< T > &	f
	)

friend

Human readable printing of a Future to a stream.

Stream output operator for a future.

Template Parameters

T	The type of future.

Parameters

[in,out]	out	The output stream.
[in]	f	The future.

Returns: The output stream.

Todo:: Brief description needed.

Todo:: Descriptions needed.

Template Parameters

T	Description needed.

Parameters

[in,out]	The	output stream.
[in]	f	The future to be output.

Returns: The output stream.

Member Data Documentation

◆ buffer

template<typename T >

char madness::Future< T >::buffer[sizeof(T)]

private

Buffer to hold a single T object.

◆ f

template<typename T >

std::shared_ptr< FutureImpl<T> > madness::Future< T >::f

private

Pointer to the implementation object.

Referenced by madness::Future< T >::Future(), madness::Future< T >::get(), madness::Future< T >::get(), madness::Future< T >::get(), madness::Future< T >::is_default_initialized(), madness::Future< T >::is_local(), madness::Future< T >::operator=(), madness::Future< T >::probe(), madness::Future< T >::register_callback(), madness::Future< T >::remote_ref(), madness::Future< T >::set(), madness::Future< T >::set(), madness::Future< T >::set(), and madness::Future< T >::set().

◆ value

template<typename T >

T* const madness::Future< T >::value

private

Pointer to buffer when it holds a T object.

Referenced by madness::Future< T >::~Future(), madness::Future< T >::get(), madness::Future< T >::get(), madness::Future< T >::get(), madness::Future< T >::is_default_initialized(), madness::Future< T >::is_local(), madness::Future< T >::operator=(), madness::Future< T >::probe(), madness::Future< T >::set(), and madness::Future< T >::set().

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

future.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ remote_refT

Constructor & Destructor Documentation

◆ Future() [1/6]

◆ Future() [2/6]

◆ Future() [3/6]

◆ Future() [4/6]

◆ Future() [5/6]

◆ Future() [6/6]

◆ ~Future()

Member Function Documentation

◆ default_initializer()

◆ get() [1/3]

◆ get() [2/3]

◆ get() [3/3]

◆ is_default_initialized()

◆ is_local()

◆ is_remote()

◆ operator const T &()

◆ operator T()

◆ operator T&()

◆ operator=()

◆ probe()

◆ register_callback()

◆ remote_ref()

◆ set() [1/4]

◆ set() [2/4]

◆ set() [3/4]

◆ set() [4/4]

Friends And Related Symbol Documentation

◆ operator<<

Member Data Documentation

◆ buffer

◆ f

◆ value