hololink::module::Publisher

Provide support for loadable modules that publish a specific set of services.

This support includes

• Lazy service instantiation with caching: The first time a request for a specific resource is observed results in a call to construct_service(). The return value is cached and returned in subsequent calls to lookup().
• Caches of common services provided by the application layer, including Logging and Reactor, and the Module presented by the application.

Exactly one Publisher may exist in an individual binary (shared object or application). Each module shared object has its own, separate from the host’s.

Lookups are thread-safe. Lookups of the same service made concurrently do not call construct_service() more than once.

#include <hololink/module/publisher.hpp>

Inherits from: std::enable_shared_from_this< Publisher > (public)

Constructors

Publisher

hololink::module::Publisher::Publisher()

Construct the binary’s Publisher.

Intended to be called from a derived class: a module’s Publisher is created in its hololink_module_init, the host’s when it starts up.

Throws: std::runtime_error if a Publisher already exists in this binary.

Methods

self_module

std::shared_ptr<Module> hololink::module::Publisher::self_module()

A Module through which this Publisher’s own services can be looked up.

Use it when code in the same binary needs the typed T::get_service(module, ...) lookup for a service published here. The returned Module keeps this Publisher alive for as long as it, or any service obtained through it, is held, so it may be retained after the code that created the Publisher has finished.

Returns: The same Module on every call.

host_module

std::shared_ptr<Module> hololink::module::Publisher::host_module() const

A Module through which a module can look up services published by the host (for example LoggingInterfaceV1 and ReactorV1).

Returns: The host’s Module once setup() has succeeded. Null before then, and always null on the host’s own Publisher.

logger

std::shared_ptr<LoggingInterfaceV1> hololink::module::Publisher::logger() const

The host’s logger.

This is the logger that the HSB_LOG_* macros use in this binary.

Returns: The logger once setup() has succeeded. Null before then, and always null on the host’s own Publisher.

reactor

std::shared_ptr<ReactorV1> hololink::module::Publisher::reactor() const

The host’s reactor.

Returns: The reactor once setup() has succeeded. Null before then, and always null on the host’s own Publisher.

setup

virtual hololink_module_services_t hololink::module::Publisher::setup(
    const hololink_module_init_t *init
)

Connect a module to the host.

Called from the module’s hololink_module_init entry point.

Checks init and, if it is acceptable, makes the host’s Module, logger and reactor available through host_module(), logger() and reactor(), and connects this binary’s HSB_LOG_* macros to the host’s logger. Subclasses may override this to publish services that must exist before any lookup; an override should call this implementation first and return its result unchanged if the status is not HOLOLINK_MODULE_OK.

Returns: The services structure to return from hololink_module_init. Its status is HOLOLINK_MODULE_INVALID_PARAMETER, without throwing, if init is null, was built for a different API version, or lacks its lookup callbacks.

Throws: std::runtime_error if the host does not provide a logger or reactor.

Parameters

construct_service

virtual bool hololink::module::Publisher::construct_service(
    const std::string &instance_id,
    const std::string &type_id
)

Create a service on demand.

Called when a lookup finds no cached service for the given identifiers. An implementation that can supply the service constructs it, publishes it under instance_id with ServicePublisher, and returns true. Construction should be cheap and must not acquire hardware or other resources; that belongs in the service’s later configuration. An implementation that has no such service returns false, and the lookup then reports the service as not found.

Calls are serialized with other lookups, and publishing other services within this call is permitted.

Returns: true if a service was published for these identifiers.

Parameters

Static methods

invalidate

static void hololink::module::Publisher::invalidate(
    const void *service
)

Discard a published service so that the next lookup creates a fresh one.

Clears the instance cache for this service; a later call to lookup for this object will return a newly constructed instance. Note that this decrements the shared_ptr reference count, so the actual instance is destructed only after the last reference is dropped. This method does nothing if service is null or was not published.

A service can invalidate itself by passing this.

Parameters

has_type_id

template <typename T>
static bool hololink::module::Publisher::has_type_id(
    const std::string &type_id
)

Report whether a service class is published under a type id.

A service class may support multiple type ids (e.g. it supports several versions of an interface or different, maybe unrelated interfaces). This method, for a given service class T, returns true if the requested type_id is in the list of those supported by T.

Returns: true if type_id is one of the type ids of T.

Template parameters

Parameters