Using the Mirror Service

Owned by Matt Raykowski
Last updated: Oct 11, 2012Version comment
4 min read

Summary

The Mirror Service is responsible for replicating data sets between multiple heterogeneous services. The CMirror class makes it possible for a service to share, access and modify the values of any property of any entity in a shard.

A property belongs to one dataset (see CMirroredDataSet) and is stored and addresses using a TPropertyIndex. An entity added in a dataset is stored and addressed using a TDataSetRow.

The mirror system handles the sharing of entities and the sharing of properties between services, using shared memory for services on the same physical machine, and network communication for remote services. It handles the notification (if required) of the service when a value has changed or an entity has been added or removed.

Several services are allowed to create distinct entities that have the same type (i.e. that will have the same dataset(s)). In a dataset, each service will have a specific range of rows to avoid conflicts. See declareEntityTypeOwner(), addEntity(), removeEntity().

The datasets are loaded at init(). They can be browsed using dsBegin() and dsEnd(), and a specific dataset can be retrieved by name, getDataSet().

The recommended way to use this class is to declare a CMirror object as a member of an instanciated singleton class. However, if you use it by declaring a static CMirror object, you must not forget to call the release() method in your release code.

Data Sets Available

There are only three primary datasets available in Ryzom Core by default.

  • pet
  • fame
  • fe_temp

Connecting a Service to MS

Callbacks

There are a number of callbacks available through the mirror system. Listed below are the available callbacks with example names. You are not required to use the callback name cbMirrorIsReadyForInit for example.

  • (Required) cbMirrorIsReadyForInit - A callback that will be executed when the mirror is ready (level 1.)
  • (Optional) cbMirrorReadyForAddEntity - A callback that will be executed when the mirror is ready (level 2.)
  • (Required) cbUpdate - A callback that will be called for each game cycle (tick.)
  • (Optional) cbSync - A callback that will be called for each tick sync (first game cycle value)
  • (Optional) cbRelease - A callback that will be called when the service has requested to exit and it's okay to remove entities.
  • (Required) cbProcessMirrorUpdates - This callback will process the notifications of entity and property changes.

Mirror Ready Callbacks

There are two stages that the mirror is ready at. These are referred to as "level 1" and "level 2" readiness.

At level 1 readiness the mirror class is ready for dataset initialization. This means identifying the entity types your service owns, the data sets you're registered for and the properties and types of property access your service desires. All of this activity must take place in your cbMirrorIsReadyForInitfunction/callback.

The callback type is defined as:

typedef void (*TMirrorReadyCallback) (CMirror*);

 

 

At level 2 readiness the mirror class is ready for the management of entities such as adding entities. All of this activity should take place in your 
cbMirrorReadyForAddEntity function/callback.

The callback type is also defined as:

typedef void (*TMirrorReadyCallback) (CMirror*);

 

 

An implementation for a level 1 mirror raedy callback would look like this:

void cbMirrorIsReady( CMirror *mirror ) { }

 

Retrieving Data Sets

Declaring Properties

You must declare what properties on a dataset that you are interested in, what your level of interest in these properties is and finally how you want notifications on property changes to be exchanged. The first parameter is self explanatory - it is a string that identifies the property name. The second parameter is a bitwise container which has a number of options:

  • PSOWriteOnly - Although it is rare use this flag if your service needs to only write some values and is not interested in the other values possibly changes by another service. This flag is incompatible with PSOReadOnly and PSOReadWrite for obvious reasons as well asPSONotifyChanges. You must use this flag with caution and only if the services that can write the property do not handle the same rows!
  • PSOReadOnly - Use this flag if the service will never need modify the value of the property.
  • PSOReadWrite - Use this flag if the service will modify and read changes of the property.
  • PSONotifyChanges - Use this flag if the service will need to be notified when a value has been changed by another service, using the notification methods. The callback used here will be your equivalent to cbProcessMirrorUpdates (explained above.) POSReadWrite will send/receive changes to properties but this flag will actually allow you to receive notification that something else has changed them.
  • PSOMonitorAssignment - Use this flag is you need extra debugging help and are in NL_DEBUG mode. The value will be displayed every time a property value is assigned in the mirror.

The third parameter is a means for grouping all notifications for properties. The default is a blank string which means that all ungrouped properties will be notified at the same time. If you want to group certain property notifications together or want a specific property to send notifications on its own you would set this string.

Here is an example of declaring properties at level 1 readiness:

void cbMirrorIsReady( CMirror *mirror )
{
    // This mirror properties are checked a each ticks
    CMirrors::DataSet = &(CMirrors::Mirror.getDataSet("fe_temp"));
    CMirrors::DataSet->declareProperty( "X", PSOReadOnly | PSONotifyChanges, "X" );
    CMirrors::DataSet->declareProperty( "Y", PSOReadOnly | PSONotifyChanges, "X" );
    CMirrors::DataSet->declareProperty( "Z", PSOReadOnly | PSONotifyChanges, "X" );
    CMirrors::DataSet->declareProperty( "Theta", PSOReadOnly | PSONotifyChanges, "X" );
}

 

Using a Data Set

TODO

Troubleshooting

  • displayMSTrackers

This command provides in depth information about which services are connected to the MS, what datasets they are subscribed too and the type of access they have to each property in the dataset.

  • displayClientServices

This command provides a summary of services connected to the MS and their current status.

  • displayRemoteMS

This will list any remote MS instance that are communicating with the active one.