VirtualBox

source: vbox/trunk/src/VBox/Main/include/AutoCaller.h@ 67954

Last change on this file since 67954 was 63147, checked in by vboxsync, 8 years ago

Main: warnings

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 15.7 KB
Line 
1/* $Id: AutoCaller.h 63147 2016-08-08 11:12:33Z vboxsync $ */
2/** @file
3 *
4 * VirtualBox object caller handling definitions
5 */
6
7/*
8 * Copyright (C) 2006-2016 Oracle Corporation
9 *
10 * This file is part of VirtualBox Open Source Edition (OSE), as
11 * available from http://www.virtualbox.org. This file is free software;
12 * you can redistribute it and/or modify it under the terms of the GNU
13 * General Public License (GPL) as published by the Free Software
14 * Foundation, in version 2 as it comes in the "COPYING" file of the
15 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
16 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
17 */
18
19#ifndef ____H_AUTOCALLER
20#define ____H_AUTOCALLER
21
22#include "ObjectState.h"
23
24#include "VBox/com/AutoLock.h"
25
26// Forward declaration needed, but nothing more.
27class VirtualBoxBase;
28
29
30////////////////////////////////////////////////////////////////////////////////
31//
32// AutoCaller* classes
33//
34////////////////////////////////////////////////////////////////////////////////
35
36
37/**
38 * Smart class that automatically increases the number of normal (non-limited)
39 * callers of the given VirtualBoxBase object when an instance is constructed
40 * and decreases it back when the created instance goes out of scope (i.e. gets
41 * destroyed).
42 *
43 * If #rc() returns a failure after the instance creation, it means that
44 * the managed VirtualBoxBase object is not Ready, or in any other invalid
45 * state, so that the caller must not use the object and can return this
46 * failed result code to the upper level.
47 *
48 * See ObjectState::addCaller() and ObjectState::releaseCaller() for more
49 * details about object callers.
50 *
51 * A typical usage pattern to declare a normal method of some object (i.e. a
52 * method that is valid only when the object provides its full
53 * functionality) is:
54 * <code>
55 * STDMETHODIMP Component::Foo()
56 * {
57 * AutoCaller autoCaller(this);
58 * HRESULT hrc = autoCaller.rc();
59 * if (SUCCEEDED(hrc))
60 * {
61 * ...
62 * }
63 * return hrc;
64 * }
65 * </code>
66 */
67class AutoCaller
68{
69public:
70 /**
71 * Default constructor. Not terribly useful, but it's valid to create
72 * an instance without associating it with an object. It's a no-op,
73 * like the more useful constructor below when NULL is passed to it.
74 */
75 AutoCaller()
76 {
77 init(NULL, false);
78 }
79
80 /**
81 * Increases the number of callers of the given object by calling
82 * ObjectState::addCaller() for the corresponding member instance.
83 *
84 * @param aObj Object to add a normal caller to. If NULL, this
85 * instance is effectively turned to no-op (where
86 * rc() will return S_OK).
87 */
88 AutoCaller(VirtualBoxBase *aObj)
89 {
90 init(aObj, false);
91 }
92
93 /**
94 * If the number of callers was successfully increased, decreases it
95 * using ObjectState::releaseCaller(), otherwise does nothing.
96 */
97 ~AutoCaller()
98 {
99 if (mObj && SUCCEEDED(mRC))
100 mObj->getObjectState().releaseCaller();
101 }
102
103 /**
104 * Returns the stored result code returned by ObjectState::addCaller()
105 * after instance creation or after the last #add() call. A successful
106 * result code means the number of callers was successfully increased.
107 */
108 HRESULT rc() const { return mRC; }
109
110 /**
111 * Returns |true| if |SUCCEEDED(rc())| is |true|, for convenience.
112 * |true| means the number of callers was successfully increased.
113 */
114 bool isOk() const { return SUCCEEDED(mRC); }
115
116 /**
117 * Temporarily decreases the number of callers of the managed object.
118 * May only be called if #isOk() returns |true|. Note that #rc() will
119 * return E_FAIL after this method succeeds.
120 */
121 void release()
122 {
123 Assert(SUCCEEDED(mRC));
124 if (SUCCEEDED(mRC))
125 {
126 if (mObj)
127 mObj->getObjectState().releaseCaller();
128 mRC = E_FAIL;
129 }
130 }
131
132 /**
133 * Restores the number of callers decreased by #release(). May only be
134 * called after #release().
135 */
136 void add()
137 {
138 Assert(!SUCCEEDED(mRC));
139 if (mObj && !SUCCEEDED(mRC))
140 mRC = mObj->getObjectState().addCaller(mLimited);
141 }
142
143 /**
144 * Attaches another object to this caller instance.
145 * The previous object's caller is released before the new one is added.
146 *
147 * @param aObj New object to attach, may be @c NULL.
148 */
149 void attach(VirtualBoxBase *aObj)
150 {
151 /* detect simple self-reattachment */
152 if (mObj != aObj)
153 {
154 if (mObj && SUCCEEDED(mRC))
155 release();
156 else if (!mObj)
157 {
158 /* Fix up the success state when nothing is attached. Otherwise
159 * there are a couple of assertion which would trigger. */
160 mRC = E_FAIL;
161 }
162 mObj = aObj;
163 add();
164 }
165 }
166
167 /** Verbose equivalent to <tt>attach(NULL)</tt>. */
168 void detach() { attach(NULL); }
169
170protected:
171 /**
172 * Internal constructor: Increases the number of callers of the given
173 * object (either normal or limited variant) by calling
174 * ObjectState::addCaller() for the corresponding member instance.
175 *
176 * @param aObj Object to add a caller to. If NULL, this
177 * instance is effectively turned to no-op (where
178 * rc() will return S_OK).
179 * @param aLimited If |false|, then it's a regular caller, otherwise a
180 * limited caller.
181 */
182 void init(VirtualBoxBase *aObj, bool aLimited)
183 {
184 mObj = aObj;
185 mRC = S_OK;
186 mLimited = aLimited;
187 if (mObj)
188 mRC = mObj->getObjectState().addCaller(mLimited);
189 }
190
191private:
192 DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP(AutoCaller);
193 DECLARE_CLS_NEW_DELETE_NOOP(AutoCaller);
194
195 VirtualBoxBase *mObj;
196 HRESULT mRC;
197 bool mLimited;
198};
199
200/**
201 * Smart class that automatically increases the number of limited callers of
202 * the given VirtualBoxBase object when an instance is constructed and
203 * decreases it back when the created instance goes out of scope (i.e. gets
204 * destroyed).
205 *
206 * A typical usage pattern to declare a limited method of some object (i.e.
207 * a method that is valid even if the object doesn't provide its full
208 * functionality) is:
209 * <code>
210 * STDMETHODIMP Component::Bar()
211 * {
212 * AutoLimitedCaller autoCaller(this);
213 * HRESULT hrc = autoCaller.rc();
214 * if (SUCCEEDED(hrc))
215 * {
216 * ...
217 * }
218 * return hrc;
219 * </code>
220 *
221 * See AutoCaller for more information about auto caller functionality.
222 */
223class AutoLimitedCaller : public AutoCaller
224{
225public:
226 /**
227 * Default constructor. Not terribly useful, but it's valid to create
228 * an instance without associating it with an object. It's a no-op,
229 * like the more useful constructor below when NULL is passed to it.
230 */
231 AutoLimitedCaller()
232 {
233 AutoCaller::init(NULL, true);
234 }
235
236 /**
237 * Increases the number of callers of the given object by calling
238 * ObjectState::addCaller() for the corresponding member instance.
239 *
240 * @param aObj Object to add a limited caller to. If NULL, this
241 * instance is effectively turned to no-op (where
242 * rc() will return S_OK).
243 */
244 AutoLimitedCaller(VirtualBoxBase *aObj)
245 {
246 AutoCaller::init(aObj, true);
247 }
248
249private:
250 DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP(AutoLimitedCaller); /* Shuts up MSC warning C4625. */
251};
252
253/**
254 * Smart class to enclose the state transition NotReady->InInit->Ready.
255 *
256 * The purpose of this span is to protect object initialization.
257 *
258 * Instances must be created as a stack-based variable taking |this| pointer
259 * as the argument at the beginning of init() methods of VirtualBoxBase
260 * subclasses. When this variable is created it automatically places the
261 * object to the InInit state.
262 *
263 * When the created variable goes out of scope (i.e. gets destroyed) then,
264 * depending on the result status of this initialization span, it either
265 * places the object to Ready or Limited state or calls the object's
266 * VirtualBoxBase::uninit() method which is supposed to place the object
267 * back to the NotReady state using the AutoUninitSpan class.
268 *
269 * The initial result status of the initialization span is determined by the
270 * @a aResult argument of the AutoInitSpan constructor (Result::Failed by
271 * default). Inside the initialization span, the success status can be set
272 * to Result::Succeeded using #setSucceeded(), to to Result::Limited using
273 * #setLimited() or to Result::Failed using #setFailed(). Please don't
274 * forget to set the correct success status before getting the AutoInitSpan
275 * variable destroyed (for example, by performing an early return from
276 * the init() method)!
277 *
278 * Note that if an instance of this class gets constructed when the object
279 * is in the state other than NotReady, #isOk() returns |false| and methods
280 * of this class do nothing: the state transition is not performed.
281 *
282 * A typical usage pattern is:
283 * <code>
284 * HRESULT Component::init()
285 * {
286 * AutoInitSpan autoInitSpan(this);
287 * AssertReturn(autoInitSpan.isOk(), E_FAIL);
288 * ...
289 * if (FAILED(rc))
290 * return rc;
291 * ...
292 * if (SUCCEEDED(rc))
293 * autoInitSpan.setSucceeded();
294 * return rc;
295 * }
296 * </code>
297 *
298 * @note Never create instances of this class outside init() methods of
299 * VirtualBoxBase subclasses and never pass anything other than |this|
300 * as the argument to the constructor!
301 */
302class AutoInitSpan
303{
304public:
305
306 enum Result { Failed = 0x0, Succeeded = 0x1, Limited = 0x2 };
307
308 AutoInitSpan(VirtualBoxBase *aObj, Result aResult = Failed);
309 ~AutoInitSpan();
310
311 /**
312 * Returns |true| if this instance has been created at the right moment
313 * (when the object was in the NotReady state) and |false| otherwise.
314 */
315 bool isOk() const { return mOk; }
316
317 /**
318 * Sets the initialization status to Succeeded to indicates successful
319 * initialization. The AutoInitSpan destructor will place the managed
320 * VirtualBoxBase object to the Ready state.
321 */
322 void setSucceeded() { mResult = Succeeded; }
323
324 /**
325 * Sets the initialization status to Succeeded to indicate limited
326 * (partly successful) initialization. The AutoInitSpan destructor will
327 * place the managed VirtualBoxBase object to the Limited state.
328 */
329 void setLimited() { mResult = Limited; }
330
331 /**
332 * Sets the initialization status to Failure to indicates failed
333 * initialization. The AutoInitSpan destructor will place the managed
334 * VirtualBoxBase object to the InitFailed state and will automatically
335 * call its uninit() method which is supposed to place the object back
336 * to the NotReady state using AutoUninitSpan.
337 */
338 void setFailed(HRESULT rc = E_ACCESSDENIED)
339 {
340 mResult = Failed;
341 mFailedRC = rc;
342 mpFailedEI = new ErrorInfo();
343 }
344
345 /** Returns the current initialization result. */
346 Result result() { return mResult; }
347
348private:
349
350 DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP(AutoInitSpan);
351 DECLARE_CLS_NEW_DELETE_NOOP(AutoInitSpan);
352
353 VirtualBoxBase *mObj;
354 Result mResult : 3; // must be at least total number of bits + 1 (sign)
355 bool mOk : 1;
356 HRESULT mFailedRC;
357 ErrorInfo *mpFailedEI;
358};
359
360/**
361 * Smart class to enclose the state transition Limited->InInit->Ready.
362 *
363 * The purpose of this span is to protect object re-initialization.
364 *
365 * Instances must be created as a stack-based variable taking |this| pointer
366 * as the argument at the beginning of methods of VirtualBoxBase
367 * subclasses that try to re-initialize the object to bring it to the Ready
368 * state (full functionality) after partial initialization (limited
369 * functionality). When this variable is created, it automatically places
370 * the object to the InInit state.
371 *
372 * When the created variable goes out of scope (i.e. gets destroyed),
373 * depending on the success status of this initialization span, it either
374 * places the object to the Ready state or brings it back to the Limited
375 * state.
376 *
377 * The initial success status of the re-initialization span is |false|. In
378 * order to make it successful, #setSucceeded() must be called before the
379 * instance is destroyed.
380 *
381 * Note that if an instance of this class gets constructed when the object
382 * is in the state other than Limited, #isOk() returns |false| and methods
383 * of this class do nothing: the state transition is not performed.
384 *
385 * A typical usage pattern is:
386 * <code>
387 * HRESULT Component::reinit()
388 * {
389 * AutoReinitSpan autoReinitSpan(this);
390 * AssertReturn(autoReinitSpan.isOk(), E_FAIL);
391 * ...
392 * if (FAILED(rc))
393 * return rc;
394 * ...
395 * if (SUCCEEDED(rc))
396 * autoReinitSpan.setSucceeded();
397 * return rc;
398 * }
399 * </code>
400 *
401 * @note Never create instances of this class outside re-initialization
402 * methods of VirtualBoxBase subclasses and never pass anything other than
403 * |this| as the argument to the constructor!
404 */
405class AutoReinitSpan
406{
407public:
408
409 AutoReinitSpan(VirtualBoxBase *aObj);
410 ~AutoReinitSpan();
411
412 /**
413 * Returns |true| if this instance has been created at the right moment
414 * (when the object was in the Limited state) and |false| otherwise.
415 */
416 bool isOk() const { return mOk; }
417
418 /**
419 * Sets the re-initialization status to Succeeded to indicates
420 * successful re-initialization. The AutoReinitSpan destructor will place
421 * the managed VirtualBoxBase object to the Ready state.
422 */
423 void setSucceeded() { mSucceeded = true; }
424
425private:
426
427 DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP(AutoReinitSpan);
428 DECLARE_CLS_NEW_DELETE_NOOP(AutoReinitSpan);
429
430 VirtualBoxBase *mObj;
431 bool mSucceeded : 1;
432 bool mOk : 1;
433};
434
435/**
436 * Smart class to enclose the state transition Ready->InUninit->NotReady,
437 * InitFailed->InUninit->NotReady.
438 *
439 * The purpose of this span is to protect object uninitialization.
440 *
441 * Instances must be created as a stack-based variable taking |this| pointer
442 * as the argument at the beginning of uninit() methods of VirtualBoxBase
443 * subclasses. When this variable is created it automatically places the
444 * object to the InUninit state, unless it is already in the NotReady state
445 * as indicated by #uninitDone() returning |true|. In the latter case, the
446 * uninit() method must immediately return because there should be nothing
447 * to uninitialize.
448 *
449 * When this variable goes out of scope (i.e. gets destroyed), it places the
450 * object to NotReady state.
451 *
452 * A typical usage pattern is:
453 * <code>
454 * void Component::uninit()
455 * {
456 * AutoUninitSpan autoUninitSpan(this);
457 * if (autoUninitSpan.uninitDone())
458 * return;
459 * ...
460 * }
461 * </code>
462 *
463 * @note The constructor of this class blocks the current thread execution
464 * until the number of callers added to the object using
465 * ObjectState::addCaller() or AutoCaller drops to zero. For this reason,
466 * it is forbidden to create instances of this class (or call uninit())
467 * within the AutoCaller or ObjectState::addCaller() scope because it is
468 * a guaranteed deadlock.
469 *
470 * @note Never create instances of this class outside uninit() methods and
471 * never pass anything other than |this| as the argument to the
472 * constructor!
473 */
474class AutoUninitSpan
475{
476public:
477
478 AutoUninitSpan(VirtualBoxBase *aObj);
479 ~AutoUninitSpan();
480
481 /** |true| when uninit() is called as a result of init() failure */
482 bool initFailed() { return mInitFailed; }
483
484 /** |true| when uninit() has already been called (so the object is NotReady) */
485 bool uninitDone() { return mUninitDone; }
486
487 void setSucceeded();
488
489private:
490
491 DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP(AutoUninitSpan);
492 DECLARE_CLS_NEW_DELETE_NOOP(AutoUninitSpan);
493
494 VirtualBoxBase *mObj;
495 bool mInitFailed : 1;
496 bool mUninitDone : 1;
497};
498
499#endif // !____H_AUTOCALLER
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette