MscmpSystService behaviour (mscmp_syst_service v0.1.0)

Establishes a Behaviour and common system or instance service patterns for the application.

A number of persistent services are needed to successfully run the Muse Systems Business Management system. Many of these services may also need to be started and run on a per-Instance basis and will thus have many of the same service selection requirements between different services. This module establishes the common patterns that individual services should implement.

For the most part, this Component establishes a Behaviour that other service defining Components should implement. This ensures that any such services can be more readily comprehended as they will implement common service patterns across the application.

To implement this behaviour into a new Service, simply add the use MscmpSystService directive to the top of the Public API module implementing the interface.

use MscmpSystService

When use MscmpSystService is called with the required options, it:

  1. Adds the MscmpSystService as a module behaviour.

  2. Adds the @service_option_defs module attribute to the module. This attribute provides the NimbleOptions schema for standard GenServer start options which are passed through to backing GenServer, assuming the Service is backed by a GenServer. Whether any given Service makes use of these options is entirely up to the Service implementation.

  3. Adds the @service_option_selections module attribute to the module. This attribute provides a pre-assembled list of the NimbleOptions selections for the standard GenServer starting options listed above.

Summary

Callbacks

child_spec(opts)

Returns the child specification of the service.

get_runtime_config()

Retrieves the runtime configuration of a previously started Service.

get_service()

Retrieves the name of the currently set Service instance.

put_service(service_name)

Establishes a specific running instance of the Service as the current service for the running process which invoked this function.

start_link(opts)

Starts the Service instance.

Callbacks

child_spec(opts)

@callback child_spec(opts :: Keyword.t()) :: Supervisor.child_spec()

Returns the child specification of the service.

Parameters

  • opts - A service may define one or more options which govern the startup behavior of the service. Options are specific to Service and may be required or optional depending on the needs of the Service.

get_runtime_config()

@callback get_runtime_config() :: map()

Retrieves the runtime configuration of a previously started Service.

Some services need a mechanism to return features such as :ets table names which are set at runtime. This callback provides the mechanism by which such runtime configuration can be returned.

get_service()

@callback get_service() :: MscmpSystService.Types.service_name()

Retrieves the name of the currently set Service instance.

See put_service/1 for more information about setting an active Service name.

Returns

Returns the name of the currently set Service name or nil if no Service name has been set.

put_service(service_name)

@callback put_service(MscmpSystService.Types.service_name()) ::
  MscmpSystService.Types.service_name()

Establishes a specific running instance of the Service as the current service for the running process which invoked this function.

Parameters

  • service_name - the name under which the Service is started and by which it may be referenced. This is any name that may be used to reference a GenServer process. Additionally, this value may be set nil to clear the currently set Service name.

Returns

Returns the name of the previously set Service or nil if no Service name had been previously set.

start_link(opts)

@callback start_link(opts :: Keyword.t()) ::
  {:ok, pid()} | :ignore | {:error, Exception.t()}

Starts the Service instance.

This function should start the underlying GenServer process and return the appropriate result tuple.

MscmpSystError Exceptions

Typically exceptions passed from an implementing service will be Exception objects which are specifically compatible with MscmpSystError exceptions. Such exceptions are defined by the service implementing module as Mserror Exception specializations.

Parameters

  • opts - Services may define either required or optional parameters which govern its startup process.