## NAME

ACE_Future - This class implements a ``single write, multiple read'' pattern that can be used to return results from asynchronous method invocations.

## SYNOPSIS

    #include <ace/Future.h>

    template<class T>
    class ACE_Future
    {
      public:
        ACE_Future (void);
        ACE_Future (const ACE_Future<T> &r);
        ACE_Future (const T &r);
        ~ACE_Future (void);
        void operator = (const ACE_Future<T> &r);
        int cancel (const T &r);
        int cancel (void);
        int operator == (const ACE_Future<T> &r) const;
        int operator != (const ACE_Future<T> &r) const;
        int set (const T &r);
        int get (T &value, ACE_Time_Value *tv = 0);
        operator T ();
        int ready (void);
        int attach (ACE_Future_Observer<T> *observer);
        int detach (ACE_Future_Observer<T> *observer);
        void dump (void) const;
        ACE_Future_Rep<T> *get_rep ();
        ACE_ALLOC_HOOK_DECLARE;
      private:
        void *operator new (size_t nbytes);
        void operator delete (void *);
        void operator & ();
        typedef ACE_Future_Rep<T> FUTURE_REP;
        FUTURE_REP *future_rep_;
    };

## Initialization and termination methods.

    ACE_Future (void);

Constructor.

    ACE_Future (const ACE_Future<T> &r);

Copy constructor binds `this` and `r` to the same `ACE_Future_Rep`. An `ACE_Future_Rep` is created if necessary.

    ACE_Future (const T &r);

Constructor that initialises an `ACE_Future` to point to the result `r` immediately.

    ~ACE_Future (void);

Destructor.

    void operator = (const ACE_Future<T> &r);

Assignment operator that binds `this` and `r` to the same `ACE_Future_Rep`. An `ACE_Future_Rep` is created if necessary.

    int cancel (const T &r);

Cancel an `ACE_Future` and assign the value `r`. It is used if a client does not want to wait for `T` to be produced.

    int cancel (void);

Cancel an `ACE_Future`. Put the future into its initial state. Returns 0 on succes and -1 on failure. It is now possible to reuse the ACE_Future`T`. But remember, the ACE_Future`T` is now bound to a new ACE_Future_Rep`T`.

    int operator == (const ACE_Future<T> &r) const;

Equality operator that returns 1 if both ACE_Future`T` objects point to the same ACE_Future_Rep`T` object. Attention: It also returns 1 if both objects have just been instantiated and not used yet.

    int operator != (const ACE_Future<T> &r) const;

Inequality operator, which is the opposite of equality.

    int set (const T &r);

Make the result available. Is used by the server thread to give the result to all waiting clients.

    int get (T &value, ACE_Time_Value *tv = 0);

Wait up to `tv` time to get the `value`. Note that `tv` must be specified in absolute time rather than relative time.

    operator T ();

Type conversion, which obtains the result of the asynchronous method invocation. Will block forever. Note that this method is going away in a subsequent release since it doesn't distinguish between failure results and success results (exceptions should be used, but they aren't portable...). The `get` method should be used instead since it separates the error value from the result, and also permits timeouts.

    int ready (void);

Check if the result is available.

    int attach (ACE_Future_Observer<T> *observer);

Attaches the specified observer to a subject (i.e. the `ACE_Future`). The update method of the specified subject will be invoked with a copy of the associated `ACE_Future` as input when the result gets set. If the result is already set when this method gets invoked, then the update method of the specified subject will be invoked immediately.

Returns 0 if the observer is successfully attached, 1 if the observer is already attached, and -1 if failures occur.

    int detach (ACE_Future_Observer<T> *observer);

Detaches the specified observer from a subject (i.e. the `ACE_Future_Rep`). The update method of the specified subject will not be invoked when the `ACE_Future_Reps` result gets set. Returns 1 if the specified observer was actually attached to the subject prior to this call and 0 if was not.

Returns 0 if the observer was successfully detached, and -1 if the observer was not attached in the first place.

    void dump (void) const;

Dump the state of an object.

    ACE_Future_Rep<T> *get_rep ();

Get the underlying `ACE_Future_Rep`*. Note that this method should rarely, if ever, be used and that modifying the undlerlying `ACE_Future_Rep`* should be done with extreme caution.

    ACE_ALLOC_HOOK_DECLARE;

Declare the dynamic allocation hooks.

## AUTHOR (S)

Andres Kruse `Andres.Kruse@cern.ch`, Douglas C. Schmidt `schmidt@cs.wustl.edu`, Per Andersson `Per.Andersson@hfera.ericsson.se`, and John Tucker `jtucker@infoglide.com`

## LIBRARY

ace