Unity Scopes API
|
The main object for query originators to access the scopes run time. More...
#include <unity/scopes/Runtime.h>
Public Member Functions | |
void | destroy () |
Shuts down the run time, reclaiming all associated resources. More... | |
RegistryProxy | registry () const |
Returns a proxy to the Registry object. More... | |
void | run_scope (ScopeBase *const scope_base, std::string const &scope_ini_file) |
Run a scope without going through the scope runner. More... | |
ObjectProxy | string_to_proxy (std::string const &s) const |
Convert a string to a proxy. More... | |
std::string | proxy_to_string (ObjectProxy const &proxy) const |
Converts a proxy to a string. More... | |
~Runtime () | |
Destroys a Runtime instance. More... | |
Static Public Member Functions | |
static UPtr | create (std::string const &configfile="") |
Instantiates the scopes run time for a client with the given (optional) configuration file. More... | |
static UPtr | create_scope_runtime (std::string const &scope_id, std::string const &configfile="") |
Create a run time for a scope. More... | |
The main object for query originators to access the scopes run time.
All interactions with the scopes run time require a Runtime object to be instantiated first. The Runtime instance controls the overall life cycle; once a Runtime instance goes out of scope, the application must not make further calls on any instance obtained via the destroyed Runtime.
The application must instantiate a Runtime object only after main()
is entered, and it must destroy the instance before leaving main()
; failure to do so results in undefined behavior.
Note that scope implementations do not need to instantiate a Runtime instance.
unity::scopes::Runtime::~Runtime | ( | ) |
|
static |
Instantiates the scopes run time for a client with the given (optional) configuration file.
The life time of the run time is under control of the caller. Letting the returned unique_ptr
go out of scope shuts down the run time.
You must not create a Runtime instance until after main()
is entered, and you must destroy it before leaving main()
(either by explicitly calling destroy(), or by letting the returned unique_ptr
go out of scope). Failure to do so causes undefined behavior.
configfile | The path name of the configuration file to use. |
If configfile is the empty string, a default configuration is used.
|
static |
Create a run time for a scope.
This method is provided for custom scoperunner implementations, for example, for scopes written in Go.
scope_id | The unique ID of the scope. If scope_id is empty, a unique ID is used. Calling create_scope_runtime("", "Runtime.ini") is equivalent to calling create("Runtime.ini") . |
configfile | The path to the run time .ini file. If empty, the default configuration is used. |
unique_ptr
to the run time instance. void unity::scopes::Runtime::destroy | ( | ) |
Shuts down the run time, reclaiming all associated resources.
Calling destroy() is optional; the destructor implicitly calls destroy() if it was not called explicitly. However, no exceptions are thrown by the destructor. If you want to log or handle any exceptions during shutdown, call destroy() explicitly before letting the unique_ptr
returned by create() go out of scope.
string unity::scopes::Runtime::proxy_to_string | ( | ObjectProxy const & | proxy | ) | const |
Converts a proxy to a string.
proxy_to_string() converts the passed proxy to a string. Note that it is typically easier to call the ObjectProxy::to_string() method to achieve the same thing. However, proxy_to_string() is needed in order to obtain a string for a null proxy (because it is not possible to invoke a member function on a null proxy).
proxy | The proxy to convert to a string. |
RegistryProxy unity::scopes::Runtime::registry | ( | ) | const |
Returns a proxy to the Registry object.
The returned proxy allows application code to interact with the registry, which provides access to the available scopes.
void unity::scopes::Runtime::run_scope | ( | ScopeBase *const | scope_base, |
std::string const & | scope_ini_file | ||
) |
Run a scope without going through the scope runner.
This method is intended to run a scope that can not be loaded via the scope runner, such as those written in languages that cannot be dynamically loaded.
scope_base | The scope implementation |
scope_ini_file | The full path of scope configuration file |
ObjectProxy unity::scopes::Runtime::string_to_proxy | ( | std::string const & | s | ) | const |
Convert a string to a proxy.
This method is intended for testing purposes. Do not use string_to_proxy() in production code! string_to_proxy() converts a string to a proxy. The returned proxy must be down-cast using dynamic_pointer_cast
to the correct type before it can be used.
s | The string to convert into a proxy. |
nullptr
, but only if the passed string represents a null proxy. Otherwise, the return value is a non-null proxy, or an exception (for example, if the proxy string did not parse correctly, or if the proxy could not be instantiated due to incorrect values inside the string).