\chapter{Futures}

This library supports the {\em future} abstraction, defined and used by
Halstead and other researchers.


{\bf Cfuture CfutureCreate()}

Returns the handle of an empty future.  The future is said to reside
on the processor that created it.  The handle is a {\em global}
reference to the future, in other words, it may be copied freely
across processors.  However, while the handle may be moved across
processors freely, some operations can only be performed on the
processor where the future resides.

{\bf Cfuture CfutureSet(Cfuture future, void *value, int nbytes)}

Makes a copy of the value and stores it in the future.  CfutureSet
may be performed on processors other than the one where the future
resides.  If done remotely, the copy of the value is created on the
processor where the future resides.

{\bf void *CfutureWait(Cfuture fut)}

Waits until the future has been filled, then returns a pointer to the
contents of the future.  If the future has already been filled, this
happens immediately (without blocking).  Caution: CfutureWait can only
be done on the processor where the Cfuture resides.  A second caution:
blocking operations (such as this one) can only be done in
user-created threads.

{\bf void CfutureDestroy(Cfuture f)}

Frees the space used by the specified Cfuture.  This also frees the
value stored in the future.  Caution: this operation can only be done
on the processor where the Cfuture resides.

{\bf void* CfutureCreateValue(int nbytes)}

Allocates the specified amount of memory and returns a pointer to it.
This buffer can be filled with data and stored into a future, using
CfutureStoreBuffer below.  This combination is faster than using
CfutureSet directly.

{\bf void CfutureStoreValue(Cfuture fut, void *value)}

Make a copy of the value and stores it in the future, destroying the
original copy of the value.  This may be significantly faster than the
more general function, CfutureSet (it may avoid copying).  This
function can {\em only} used to store values that were previously
extracted from other futures, or values that were allocated using
CfutureCreateValue.

{\bf void CfutureModuleInit()}

This function initializes the futures module.  It must be called once
on each processor, during the handler-registration process (see the
\converse{} manual regarding CmiRegisterHandler).

