unity.scopes.Runtime

The main object for query originators to access the scopes runtime. More...

#include <unity/scopes/Runtime.h>

Public Member Functions

void destroy ()
 Shuts down the runtime, 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 runtime 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 runtime for a scope. More...
 

Detailed Description

The main object for query originators to access the scopes runtime.

All interactions with the scopes runtime 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.

Constructor & Destructor Documentation

unity::scopes::Runtime::~Runtime ( )

Destroys a Runtime instance.

The destructor implicitly calls destroy() if the application code does not explicitly destroy the instance. You must not permit a Runtime instance to persist beyond the end of main(); doing so has undefined behavior.

Member Function Documentation

Runtime::UPtr unity::scopes::Runtime::create ( std::string const &  configfile = "")
static

Instantiates the scopes runtime for a client with the given (optional) configuration file.

The life time of the runtime is under control of the caller. Letting the returned unique_ptr go out of scope shuts down the runtime.

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.

Parameters
configfileThe path name of the configuration file to use.

If configfile is the empty string, a default configuration is used.

Runtime::UPtr unity::scopes::Runtime::create_scope_runtime ( std::string const &  scope_id,
std::string const &  configfile = "" 
)
static

Create a runtime for a scope.

This method is provided for custom scoperunner implementations, for example, for scopes written in Go.

Parameters
scope_idThe 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").
configfileThe path to the runtime .ini file. If empty, the default configuration is used.
Returns
A unique_ptr to the runtime instance.
void unity::scopes::Runtime::destroy ( )

Shuts down the runtime, 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).

Parameters
proxyThe proxy to convert to a string.
Returns
The string representation of the proxy.
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.

Parameters
scope_baseThe scope implementation
scope_ini_fileThe 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.

Parameters
sThe string to convert into a proxy.
Returns
The converted proxy. It is possible for the return value to be 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).