2
* Copyright (C) 2013 Canonical Ltd
4
* This program is free software: you can redistribute it and/or modify
5
* it under the terms of the GNU General Public License version 3 as
6
* published by the Free Software Foundation.
8
* This program is distributed in the hope that it will be useful,
9
* but WITHOUT ANY WARRANTY; without even the implied warranty of
10
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11
* GNU General Public License for more details.
13
* You should have received a copy of the GNU General Public License
14
* along with this program. If not, see <http://www.gnu.org/licenses/>.
16
* Authored by: Michi Henning <michi.henning@canonical.com>
19
#ifndef UNITY_API_SCOPES_SCOPEBASE_H
20
#define UNITY_API_SCOPES_SCOPEBASE_H
22
#include <unity/util/NonCopyable.h>
23
#include <unity/api/scopes/Version.h>
39
\brief Base class for a scope implementation.
41
Scopes are provided to the Unity run time by providing them in a shared library (one library per scope).
42
Each scope must implement a class that derives from ScopeBase, for example:
45
#include <unity/api/scopes/ScopeBase.h>
47
class MyScope : public unity::api::scopes::ScopeBase
53
virtual void initialize();
54
virtual void finalize();
57
virtual void stop(); // Optional
61
The derived class must provide implementations of the pure virtual methods initialize(), finalize(), and start();
62
In addition, the librarya must provide two functions with "C" linkage. The create function must return a pointer to
63
the derived instance, which the Unity run time passes back to the destroy function before the scope library is
64
unloaded. Typically, the create and destroy functions will simply call new and delete, respectively. (However,
65
there is no requirement that the derived class instance must be heap allocated.
67
Rather than hard-coding the names of the functions, use the #UNITY_API_SCOPE_CREATE_FUNCTION and
68
#UNITY_API_SCOPE_DESTROY_FUNCTION macros, for example:
71
unity::api::scopes::ScopeBase*
72
UNITY_API_SCOPE_CREATE_FUNCTION()
74
return new MyScope; // Example only, heap-allocation is not mandatory
78
UNITY_API_SCOPE_DESTROY_FUNCTION(unity::api::scopes::ScopeBase* scope)
80
delete scope; // Example only, heap-allocation is not mandatory
84
After the Unity run time has obtained a pointer to the class instance from the create function, it calls initialize(),
85
followed by start(), which passes the thread of control to the scope implementation. When the scope should complete
86
its activities, the run time calls stop(). Once stop() (which may be overridden by the derived class) returns,
87
the run time calls finalize(). The calls to initialize(), start(), and finalize() are made by the same thread.
88
(However, stop() is called by a different thread.)
89
Once finalize() completes, the run time calls the destroy function and then unloads the library from memory.
91
The implementation of the scope is free to use the thread that calls start() in any way it deems fit, such as
92
to run an event loop. If the implementation of start() does not need to use the thread calling start(),
93
the implementation can call run(). run() blocks the calling thread until the run time has called stop()
94
and stop() has completed, at which point run() unblocks the calling thread and returns.
95
The derived class can override stop() to, for example, arrange for its event loop to terminate and join with
96
any threads it has created.
104
class UNITY_API ScopeBase : private util::NonCopyable
108
virtual ~ScopeBase();
112
Called by the Unity run time after loading the scope's library. If initialize() throws an exception,
113
start() and finalize() will _not_ be called.
115
virtual void initialize() = 0;
118
Called by the Unity run time after stop() completes. Exceptions from finalize() are ignored.
120
virtual void finalize() = 0;
123
Called by the Unity run time after initialize() completes. If start() throws an exception, stop()
124
will _not_ be called (but finalize() _will_ be called).
126
virtual void start() = 0;
129
Called by the Unity run time when the scope should shut down. Exceptions from stop() are ignored.
134
This method suspends the calling thread, so run() blocks the caller. The call completes after the Unity
135
run time has called stop() and stop() has returned.
140
This method returns the version information for the scopes API that the scope was compiled with.
142
void compiled_version(int& v_major, int& v_minor, int& v_micro) noexcept;
145
This method returns the version information for the scopes API that the scope was linked with.
147
void runtime_version(int& v_major, int& v_minor, int& v_micro) noexcept;
155
std::unique_ptr<internal::ScopeBaseImpl> p_;
158
// We inline this function so we are guaranteed to be returned the version of the scopes library that the derived
159
// class was compiled with.
164
compiled_version(int& v_major, int& v_minor, int& v_micro) noexcept
166
v_major = UNITY_SCOPES_VERSION_MAJOR;
167
v_minor = UNITY_SCOPES_VERSION_MINOR;
168
v_micro = UNITY_SCOPES_VERSION_MICRO;
171
} // namespace scopes
178
Expands to the identifier of the scope creation function. @hideinitializer
180
#define UNITY_API_SCOPE_CREATE_FUNCTION unity_api_scope_create
183
Expands to the identifier of the scope destroy function. @hideinitializer
185
#define UNITY_API_SCOPE_DESTROY_FUNCTION unity_api_scope_destroy
188
extern "C" unity::api::scopes::ScopeBase* UNITY_API_SCOPE_CREATE_FUNCTION();
189
extern "C" void UNITY_API_SCOPE_DESTROY_FUNCTION(unity::api::scopes::ScopeBase*);
added
removed
include/unity/api/scopes/ScopeBase.h
