OnixS C++ FIX Engine  4.2.0
API Documentation
Future.h
Go to the documentation of this file.
1 /*
2 * Copyright Onix Solutions Limited [OnixS]. All rights reserved.
3 *
4 * This software owned by Onix Solutions Limited [OnixS] and is protected by copyright law
5 * and international copyright treaties.
6 *
7 * Access to and use of the software is governed by the terms of the applicable OnixS Software
8 * Services Agreement (the Agreement) and Customer end user license agreements granting
9 * a non-assignable, non-transferable and non-exclusive license to use the software
10 * for it's own data processing purposes under the terms defined in the Agreement.
11 *
12 * Except as otherwise granted within the terms of the Agreement, copying or reproduction of any part
13 * of this source code or associated reference material to any other location for further reproduction
14 * or redistribution, and any amendments to this copyright notice, are expressly prohibited.
15 *
16 * Any reproduction or redistribution for sale or hiring of the Software not in accordance with
17 * the terms of the Agreement is a violation of copyright law.
18 */
19 
20 #pragma once
21 
22 #include <OnixS/FIXEngine/ABI.h>
24 
25 #include <stdexcept>
26 
27 namespace OnixS {
28 namespace Threading {
29 
30 /// Represents a future result of an asynchronous operation.
31 /// `SharedFuture` is copyable and multiple shared objects may refer to the same shared state.
32 ///
33 /// @note Access to the same shared state from multiple threads is safe if each thread does it through its own copy of a `SharedFuture` object.
35 {
36 public:
37 
38  /// Constructor.
39  /// Constructs a `SharedFuture` object with no shared state.
40  SharedFuture();
41 
42  /// Copy constructor.
43  /// Share the internal state with other `SharedFuture` object.
44  SharedFuture(const SharedFuture & other);
45 
46  /// Assignment operator.
47  /// Share the internal state with other `SharedFuture` object.
48  SharedFuture & operator= (const SharedFuture & other);
49 
50  /// Cleans up internal resources.
51  ~SharedFuture();
52 
53  /// Checks if the future refers to a shared state.
54  bool valid();
55 
56  /// Returns the result. If the result is not ready, the method will block. When completes, it either returns or throws an exception.
57  /// Throws an exception if an exception was stored in the shared state of this `SharedFuture` object (e.g. via `Promise::setException()`).
58  void get() const;
59 
60  /// Returns the result value. If the result is not ready, the method will block. When completes, it either returns or throws an exception.
61  /// Throws an exception if an exception was stored in the shared state of this `SharedFuture` object (e.g. via `Promise::setException()`).
62  ///
63  /// @note The requested value type ('ValueType') should correspond to the stored, by the `Promise::setValue()`, value type.
64  ///
65  /// @throw std::logic_error if the stored value type does not correspond to the requested value type ('ValueType').
66  template<typename ValueType>
67  ValueType get() const
68  {
69  return Value<ValueType>::value(getValue().value());
70  }
71 
72  /// Waits for the result to become available during the timeout.
73  void wait(const int waitInMs = InfiniteTimeout) const;
74 
75 private:
76 
77  /// Implementation details.
78  class ValueBase
79  {
80  public:
81 
82  virtual ~ValueBase() {}
83  virtual ValueBase * clone() const = 0;
84  virtual size_t typeId() const = 0;
85  };
86 
87  /// Implementation details.
88  class FutureValue
89  {
90  public:
91 
92  FutureValue(ValueBase * value);
93  FutureValue();
94  FutureValue(const FutureValue & other);
95  ~FutureValue();
96 
97  ValueBase * value() const { return value_; }
98 
99  private:
100 
101  ValueBase * value_;
102  };
103 
104  /// Implementation details.
105  template<typename ValueType>
106  class Value : public ValueBase
107  {
108  typedef Value<ValueType> Type;
109 
110  public:
111 
112  static size_t id()
113  {
114  return reinterpret_cast<size_t>(&id_);
115  }
116 
117  static ValueType value(const ValueBase * value)
118  {
119  if (!value || value->typeId() != Value<ValueType>::id())
120  throw std::logic_error("Value type mismatch.");
121 
122  return static_cast<const Type*>(value)->value();
123  }
124 
125  static ValueBase * create(const ValueType & value)
126  {
127  return new Type(value);
128  }
129 
130  virtual ValueBase * clone() const
131  {
132  return create(value_);
133  }
134 
135  virtual size_t typeId() const
136  {
137  return id();
138  }
139 
140  private:
141 
142  explicit Value(const ValueType & value) : value_(value) {}
143 
144  ValueType value() const { return value_; }
145 
146  const ValueType value_;
147 
148  static char id_;
149  };
150 
151  /// Implementation details.
152  const FutureValue & getValue() const;
153 
154  /// Implementation details.
155  struct Impl;
156  Impl * impl_;
157 
158  /// Initializes the instance.
159  /// Only the 'Promise' class is allowed to create valid `SharedFuture` objects.
160  SharedFuture(const Impl & impl);
161 
162  friend class Promise;
163 };
164 
165 template<typename ValueType>
166 char SharedFuture::Value<ValueType>::id_;
167 
168 /// Provides a facility to store a value or an exception that can be acquired asynchronously via a `SharedFuture` object created by the `Promise` object.
169 /// Each `Promise` object is associated with a shared state, which contains some state information and a result which may be not yet evaluated, evaluated to a value or evaluated to an exception.
170 /// The promise stores the result or the exception in the shared state. Marks the state ready and unblocks any thread waiting on a future associated with the shared state.
172 {
173 public:
174 
175  /// Initializes the instance.
176  Promise();
177 
178  /// Copy constructor.
179  /// Share the internal state with other `Promise` object.
180  Promise(const Promise & other);
181 
182  /// Cleans up internal resources.
183  ~Promise();
184 
185  /// Returns a `SharedFuture` object associated with this `Promise` object.
186  SharedFuture getFuture() const;
187 
188  /// Sets the successful result to the given shared state.
189  void set();
190 
191  /// Sets the successful result value to the given shared state.
192  ///
193  /// @note The stored value type ('ValueType') should correspond to the requested, by the `SharedFuture::getValue()`, value type.
194  template<typename ValueType>
195  void set(const ValueType & value)
196  {
197  setValue(SharedFuture::Value<ValueType>::create(value));
198  }
199 
200  /// Sets the result to indicate an exception.
201  ///
202  /// @note Does nothing if the shared state already stores a value or exception.
203  template<typename ExceptionType>
204  void setException(const ExceptionType & exception)
205  {
206  try
207  {
208  throw exception;
209  }
210  catch(...)
211  {
212  setException();
213  }
214  }
215 
216 private:
217 
218  // Implementation details.
219  void setValue(SharedFuture::ValueBase * value);
220 
221  // Implementation details.
222  void setException();
223 
224  /// Implementation details.
225  struct Impl;
226  Impl * impl_;
227 
228  // Assignment is prohibited.
229  Promise & operator = (const Promise &);
230 };
231 
232 }
233 }
void setException(const ExceptionType &exception)
Sets the result to indicate an exception.
Definition: Future.h:204
Represents a future result of an asynchronous operation.
Definition: Future.h:34
#define ONIXS_FIXENGINE_API
Definition: ABI.h:45
Provides a facility to store a value or an exception that can be acquired asynchronously via a Shared...
Definition: Future.h:171