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.

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.

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:

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

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.

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

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