VirtualBox

source: vbox/trunk/src/VBox/Main/include/ObjectState.h@ 86115

Last change on this file since 86115 was 82968, checked in by vboxsync, 5 years ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 5.3 KB
Line 
1/* $Id: ObjectState.h 82968 2020-02-04 10:35:17Z vboxsync $ */
2/** @file
3 *
4 * VirtualBox object state handling definitions
5 */
6
7/*
8 * Copyright (C) 2006-2020 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 MAIN_INCLUDED_ObjectState_h
20#define MAIN_INCLUDED_ObjectState_h
21#ifndef RT_WITHOUT_PRAGMA_ONCE
22# pragma once
23#endif
24
25#include "VBox/com/defs.h"
26#include "VBox/com/AutoLock.h"
27#include "VBox/com/ErrorInfo.h"
28
29// Forward declaration needed, but nothing more.
30class VirtualBoxBase;
31
32////////////////////////////////////////////////////////////////////////////////
33//
34// ObjectState
35//
36////////////////////////////////////////////////////////////////////////////////
37
38/**
39 * Thec functionality implemented by this class is the primary object state
40 * (used by VirtualBoxBase and thus part of all API classes) that indicates
41 * if the object is ready to serve the calls, and if not, what stage it is
42 * currently at. Here is the primary state diagram:
43 *
44 * +-------------------------------------------------------+
45 * | |
46 * | (InitFailed) -----------------------+ |
47 * | ^ | |
48 * v | v |
49 * [*] ---> NotReady ----> (InInit) -----> Ready -----> (InUninit) ----+
50 * ^ |
51 * | v
52 * | Limited
53 * | |
54 * +-------+
55 *
56 * The object is fully operational only when its state is Ready. The Limited
57 * state means that only some vital part of the object is operational, and it
58 * requires some sort of reinitialization to become fully operational. The
59 * NotReady state means the object is basically dead: it either was not yet
60 * initialized after creation at all, or was uninitialized and is waiting to be
61 * destroyed when the last reference to it is released. All other states are
62 * transitional.
63 *
64 * The NotReady->InInit->Ready, NotReady->InInit->Limited and
65 * NotReady->InInit->InitFailed transition is done by the AutoInitSpan smart
66 * class.
67 *
68 * The Limited->InInit->Ready, Limited->InInit->Limited and
69 * Limited->InInit->InitFailed transition is done by the AutoReinitSpan smart
70 * class.
71 *
72 * The Ready->InUninit->NotReady and InitFailed->InUninit->NotReady
73 * transitions are done by the AutoUninitSpan smart class.
74 *
75 * In order to maintain the primary state integrity and declared functionality
76 * the following rules apply everywhere:
77 *
78 * 1) Use the above Auto*Span classes to perform state transitions. See the
79 * individual class descriptions for details.
80 *
81 * 2) All public methods of subclasses (i.e. all methods that can be called
82 * directly, not only from within other methods of the subclass) must have a
83 * standard prolog as described in the AutoCaller and AutoLimitedCaller
84 * documentation. Alternatively, they must use #addCaller() and
85 * #releaseCaller() directly (and therefore have both the prolog and the
86 * epilog), but this is not recommended because it is easy to forget the
87 * matching release, e.g. returning before reaching the call.
88 */
89class ObjectState
90{
91public:
92 enum State { NotReady, Ready, InInit, InUninit, InitFailed, Limited };
93
94 ObjectState(VirtualBoxBase *aObj);
95 ~ObjectState();
96
97 State getState();
98
99 HRESULT addCaller(bool aLimited = false);
100 void releaseCaller();
101
102 bool autoInitSpanConstructor(State aExpectedState);
103 void autoInitSpanDestructor(State aNewState, HRESULT aFailedRC, com::ErrorInfo *aFailedEI);
104 State autoUninitSpanConstructor(bool fTry);
105 void autoUninitSpanDestructor();
106
107private:
108 ObjectState();
109
110 void setState(State aState);
111
112 /** Pointer to the managed object, mostly for error signalling or debugging
113 * purposes, not used much. Guaranteed to be valid during the lifetime of
114 * this object, no need to mess with refcount. */
115 VirtualBoxBase *mObj;
116 /** Primary state of this object */
117 State mState;
118 /** Thread that caused the last state change */
119 RTTHREAD mStateChangeThread;
120 /** Result code for failed object initialization */
121 HRESULT mFailedRC;
122 /** Error information for failed object initialization */
123 com::ErrorInfo *mpFailedEI;
124 /** Total number of active calls to this object */
125 unsigned mCallers;
126 /** Posted when the number of callers drops to zero */
127 RTSEMEVENT mZeroCallersSem;
128 /** Posted when the object goes from InInit/InUninit to some other state */
129 RTSEMEVENTMULTI mInitUninitSem;
130 /** Number of threads waiting for mInitUninitDoneSem */
131 unsigned mInitUninitWaiters;
132
133 /** Protects access to state related data members */
134 util::RWLockHandle mStateLock;
135
136private:
137 DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP(ObjectState); /* Shuts up MSC warning C4625. */
138};
139
140#endif /* !MAIN_INCLUDED_ObjectState_h */
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