Safir SDK Core User’s Guide

From the user perspective the Dob itself consists of two parts that together provide the object distribution mechanism. These two parts are the type system (Dots), which provides the language independent types and manages the definitions of the objects to distribute, and the distribution mechanism (Dose), which does the actual data disfstart an d sttribution and synchronisation.

To use the Dob an application includes the language specific interface part of the Dob interface into the application. This language specific interface in turn uses language independent libraries (written in C++) to manage the objects and to communicate with other parts of the Dob.

To run the Dob there is an executable, "safir_control", that must be running. This executable is responsible launching and monitoring the process that manages the distribution of data between applications and nodes in the system.

Within a node all data distribution is done through shared memory, and between the nodes it is UDP/IP communication (with a reliable protocol on top, to guarantee delivery).

Messages are data that any application can subscribe to and any application can send. Messages do not have owners in any useful sense. When an application sends a message, the Dob forwards it to all subscribers of that message.

No record is kept of messages, i.e. they are not stored in the Dob in any way. So once the message has been sent there is no way of getting hold of it again.

Messages do not have guaranteed delivery. If some application cannot keep up with the rate of messages it will miss messages. If you need guaranteed delivery, messages are not what you are looking for.

A Service has one or more handlers (known as a Service Handler) to which any application (known as a Requestor) can send service requests. For each service request that is sent, a response is received. The response is sent by the Service Handler, and should indicate the result of the operation (i.e. success or failure, with or without result data). If the service handler does not send a response within a reasonable amount of time (configurable, see [request_timeout_config]), the Dob will send a timeout response to the requestor.

Service requests and responses are guaranteed to be delivered. And you are guaranteed a response if you have sent a request, even if it may be a timeout response if the handler is overloaded.

An entity is a class of which there can be objects (known as instances) that are stored in the Dob and has one (and only one) owner. Only the owner is allowed to modify the object. Any application can subscribe for a entity instances, which means that it will receive updates whenever the instances are changed. Applications can also send requests (very similar to the service requests above) to the entity owner asking it to change something in the object.

Entity requests and responses are guaranteed to be delivered. And you are guaranteed a response if you have sent a request (this may be a timeout response, just as for service requests, as described above). Entity updates are guaranteed to reach all subscribers, with one important caveat; subscribers are not guaranteed to see all intermediate states of an entity. E.g. if an application misses one update the next update will look as if both things changed at once.

The Dob allows each application/component that wants to provide a Dob interface (as in a Service, Message or Entity that other applications/components can use) to contribute to the information model by specifying its objects in xml files, which are built into the information model.

The xml files are used to generate language interfaces, that any application that wishes to use an object can include and use.

The Dob type system also has definitions for the SI units. This makes it easier to specify what values are expected in objects. If a member is called "Angle" it should have a type of Radian32; this makes it easy for object users to know what to expect from the member. If it had been defined as a Float32 the users would have to find out from somewhere else what the expected contents are supposed to be; should there be radians, degrees, gons or mils in there?

The SI unit types are all based on Float32 or Float64 respectively:

The InstanceId, ChannelId and HandlerId types are hashed types. They can be defined either as a string or as a number. If defined as a number the number will be used as the value, but if defined by a string, the string is hashed and the hash is used as the value.

If a string is used to define hashed type, the string will be included in the type, but is only meant to be used for reference (the hash value is used for all built-in operations). There is a method on all the hashed types, RemoveString, that removes the string to save space/bandwidth.

Binary is a simple type that can be used for binary data of any size. When the Binary type is used in parameters and xml or json serialized objects, the data is encoded to base64 format.

A parameter can also be an array of values, as shown below, where one array parameter of strings and one array parameter of entityIds are defined with two values each.

Array indexing starts at 0 when accessing the values from code.

In previous versions of Safir SDK Core the array parameter syntax was a bit more bulky. For backward compatibility the old syntax is still supported but is considered deprecated. The example below shows a parameter declaration in the old format.

A parameter can also be a dictionary of key/value pairs, as shown in the example below.

Parameters can also contain whole Dou-defined objects, not just the basic types. Below is an example from Safir.Dob.NodeParameters, where there is in fact an array of items in a parameter.

Each index in the array contains the xml serialization of an instance of the Safir.Dob.NodeDefinition item (which currently only contains one member, the node name). Of course this can be done in non-array parameters as well, just leave out all the array stuff.

One interesting feature is that you can put any item that derives from Safir.Dob.NodeDefinition into this array (that is the reason for the redundant specification of the type attribute in the objects). The type attribute is only needed when you want to put an instance of a derived type into the member or array element, otherwise it is redundant.

For parameters it is also possible to use environment variables in the parameter value.

The syntax for environment variables is $(ENVIRONMENT_VARIABLE_NAME), and there can be several environment variables in one parameter. An example use is shown below.

Remember that all parameters are loaded when the first application that uses parameters starts, so any environment variables set after that time will not be seen by the type system environment variable expansion.

There is also support for special variable expansion using the same syntax as is described in [special_variables]. Special variables have built in magic in order to make them easy to use, for example when specifying operating system paths in parameters.

To use the property you need to have an object of a type that is mapped to it. For example you could have set up a subscription to Capabilities.Vehicles.Vehicle (which is mapped to the NamedObject property).

Note that in the code above there is no reference at all to what kind of object obj is. It could be any object that has the property mapped to it. It is possible to check if an object has a specific property mapped to it using the HasProperty method on the property.

As hinted to above it is possible to have many safir_generated library modules, that have dependencies on each other. Naturally circular dependencies are not allowed.

If you build all your safir_generated library modules in one CMake “build tree”, you only have to specify the dependencies using the DEPENDENCIES argument as described. But if you are building library modules separately, you will also have to tell the typesystem where to find other library modules that you depend on. Dobmake uses information in typesystem.ini - as described in [typesystem_ini] - to find library module dependencies that it cannot find within the current CMake build tree.

If you download the Safir SDK Core source code you can find an example of a dobmake/CMake build tree under src/dots/dots_dobmake.ss/tests/tree.

Dobmake is really only a gui for building and installing a CMake project. In fact, it can be used to build any CMakeLists.txt file. [dobmake] shows dobmake running under Windows 7.

To build a CMake project, enter the path to the CMakeLists.txt file in the Dou directory field (or select the CMakeLists.txt file using the browse button). Most likely you should leave the Build configs settings unchanged. You should now be able to press the Build button to generate code and build it.

If you’re using absolute install paths in your CMakeLists.txt file you can select Absolute and then press Build & Install to also install the results to the directories you specified. If you’re using relative install paths you first need to specify a CMAKE_INSTALL_PREFIX, using the Prefix field.

If you want to run dobmake from a script or from the command line, use dobmake-batch (or dobmake-batch.py on Windows) to run without using the GUI.

The dobmake-batch script expects to be run from the directory containing the CMakeLists.txt file, and CMAKE_INSTALL_PREFIX can be set using the --install argument.

The design approach is that the generated code should make use of the language’s own features in the best possible way. Languages that support operator overloading should use them if it makes the interface “better”, and languages that support properties should use them. This makes each language interface “as good as it can possibly be”, but it has one obvious side effect, i.e. the interfaces are not identical.

The syntax for operating on top-level members in the different languages is shown in [cpp-top-level], [cs-top-level] and [java-top-level]. The code is identical, except in the C++ example, where some alternative ways of accomplishing the same thing is shown.

(The attentive reader will notice the pointer stuff in the C++ examples. This is because the SDK uses smart pointers to manage memory in languages without a garbage collector. See [smart-pointers] for some info on smart pointers).

The "extra level" to get to the actual values, e.g. the GetVal() bit in C++ and Val bit in C# is needed due to the fact that the value is contained, together with the change and null flags, in a container. That there are two different ways of doing the operations in C++ is because of a clever C++ construction, proxy objects, combined with operator overloading. More on containers and proxies later.

C# and Java has only one way of doing the operations, and the C# interface uses properties for accessing the values - not as in Dob properties, but as in the language construct. (Look it up in your favourite C# reference if you don’t know what they are.)

Things get a bit more interesting when accessing nested members, see [cpp-nested], [cs-nested] and [java-nested], that show operations on nested members in the different languages.

Casting objects up and down in the inheritance hierarchy also differs between the languages, see [type_casting] for more information.

As mentioned in other parts of this document each member in a class has two flags associated with it; the IsNull flag and the IsChanged flag. To associate these flags with the value all three (the value and the two flags) are all put inside a container. The container has functions for getting and setting the value (which check/update the flags) and for changing the flags.

There are containers for all of the types in the Dob, e.g. Int32Container, Float64Container EntityIdContainer, and so on. There are also containers for user-generated types (classes and enums), and they are defined in the auto-generated code, so in the above example there would be a definition of AContainer and BContainer.

The members of the class A would be of type BContainer and Float32Container, and B’s would be of type Int64Container.

The containers introduce an extra level of indirection, which shows itself in the "GetVal()", "SetVal()" and "Val" parts of the expressions above. This unfortunately has the effect of cluttering up the code a bit, so to reduce this cluttering (in C++, which is the only supported language where it is possible) container proxies with operator overloading were introduced. They are really just an intermediate object that allows safe use of operator overloading, and they are what allows "myA.MyB()->MyInt().SetVal(3)" to be replaced with "myA.MyB()->MyInt() = 3" (as shown in the examples above). The proxies are meant to be transparent, but they do not have all operations overloaded, so for example if you’re manipulating a string, you will probably have to do GetVal() to be able to get to most of the string operations.

Note that these proxies (container proxies) should not be confused with the proxies that the Dob passes to the applications in the distribution callbacks. The Container Proxies are only meant to simplify use of the typesystems containers, whereas the proxies in the distribution callbacks are used to encapsulate a collection of data and metadata into a single object for the callback (basically allowing the callback to take just a few arguments, instead of a whole bunch, where most applications only use a few).

The generated classes are allocated on the heap and then handled via pointers. Using pointers to objects is necessary for polymorphism to work properly in the Dob interfaces.

For C++, which is not a garbage collected language, we use the smart pointer concept. Smart pointers are pointer wrapper objects that store pointers to dynamically allocated objects. They keep track of how many references there are to a certain object, and automatically deletes the referenced object when there are no more references to it.

In C# and Java there is no need for smart pointers, since both these languages have garbage collection.

Since the Dob types use inheritance any application that uses the Dob will have to do a lot of type casting. It is very important to understand how this is done, otherwise your application is likely to behave in very strange and unexpected ways.

For the discussion in this section the object hierarchy in [example_object_hierarchy] is used.

As mentioned before ([member_flags]) each member inside a Dob object (i.e. Entity, Message, Service, and Item, but not Struct, see [items_and_structs]) has two flags associated with it, an IsNull flag and an IsChanged flag (often called a null flag and a change flag, respectively).

The distribution mechanism uses the change flags to provide meaningful change information in the different distribution mechanisms, which you can read more about in [interpreting_change_flags]. This section covers only how the change flags work inside an object inside one single process.

When an object is created all change flags are set to false. When a method to change a members value is called the change flag for that member is set to true (even if the value was the same as before, i.e. it didn’t change!). If the value is changed to null (via SetNull()) it is also set to true.

If a member inside an item inside an object is changed only the change flag on the nested member is set.

The change flags' values can be checked using the IsChanged()-methods on the members. In the case of a simple member (i.e. not an item) the flag’s value is received, but in the case of an item true is returned if any one of the item’s members are changed. So IsChanged on an item member is recursive! If you need to find out if a change flag is set on the member itself, rather than on one of its members you can use IsChangedHere().

An example to make this clearer:

We have two types, MyObject and MyItem ([my_object] and [my_item]), where MyObject contains among other things an item of type MyItem.

If we have an object with change flags set like in [object_with_changeflags] (note that member C has a change flag of its own as well as a change flag for each member in it) the result of the calls to IsChanged would be like in [ischanged_results].

There are also methods to explicitly set the change flags, SetChanged(bool) and SetChangedHere(bool). As in the case of IsChanged the SetChanged-method on items is recursive, so if you need to change only the flag on the item itself you will have to use SetChangedHere. (In fact the above example could only be produced from a newly created object using some SetChanged methods).

So, what of all this stuff do you need to use? Probably only the IsChanged() method. All the other stuff is mostly used behind the scenes by the Dob to weave its magic. But there may be times that you have to do something like this.

All objects of types defined by dou files can be serialized to and from XML and JSON format (JSON support was introduced in Safir SDK Core 5.0). Methods for serialization and deserialization of objects are found in Safir.Dob.Typesystem.Serialization.

Some notes on the XML serialization:

Some notes on the JSON serialization:

The reflection interface can be used to interrogate (and modify) anonymous Objects about their member names, types and values. This is something that not many applications should have to do, and therefore it is not described fully in this document.

But here are some hints:

Use with care! or even better: With great power comes great responsibility!

When a connection is opened a separate thread is started in the application. This thread, known as the dispatch thread listens to a shared memory event which signals that something has happened that the application needs to know about, e.g. a message that the application is subscribing to has arrived. When this event is triggered, the dispatch thread calls the OnDoDispatch callback of the Dispatcher consumer.

When this happens the application must notify (through an event or some other mechanism) the thread that the connection was started in that it should call Dispatch on the connection. When the Dispatch method is called the Dob will call all “pending” callbacks, e.g. OnMessage for received messages.

The reason for all this is to make things easier for the application developer as well as removing the need for the Dob connection to be thread safe (which would inevitably make it less efficient and slower).

The upshot is that all callbacks (except, of course, the OnDoDispatch one) are called from the same thread that opened the connection, which means that most applications should not have to worry at all about locking and having multiple threads.

Important: Do the thread switch as described above, or things will probably crash in surprising ways.

[dispatching_sequence_diagram] shows the dispatching sequence.

If you’re using C++ and Boost.Asio or ACE the SDK provides Dispatcher classes that do the thread switch and calls Dispatch, see [dispatcher_classes].

Whereas a primary connection is a real connection to the Dob, a secondary connection is only a "handle" to a primary connection.

Each application needs one primary connection (at least, see [multithreading]). This connection is the one that the Dob knows about and through which data is dispatched. A secondary connection is used by other parts of the application to "attach" to the primary connection.

The reason for providing this functionality is so that for example a C++ library used by a C# application can use the main programs connection. This would otherwise be impossible, since passing the connecton object over the C# to C++ interface is not possible. Instead modules can attach to the main program’s connection using a secondary connection.

When creating a secondary connection you can either specify a connection name and instance to get a specific connection instance, or not specify anything at all, in which case you will be given the first connection that was created in the current thread.

The Dob uses logical addressing for its distribution mechanisms, which means that you use a logical name for which applications to send messages to, for example.

There are two concepts that we’ll introduce here (they’re described in greater detail later), channels and handlers.

A channel is like an FM radio frequency; when you send, you’re sending on a particular frequency, and when you’re receiving, you’re listening to a particular frequency. When you send messages, you send them on a channel, and when you subscribe to messages, you subscribe to a particular channel (or all channels, which is where the analogy isn’t quite as good any more).

A handler is the concept that is used for addressing requests (both service and entity requests). A handler is more like a telephone number where only one person can have a particular telephone number (and has to register with the phone company to have it), but anyone can phone that person, as long as they know the number. To be able to receive service and entity requests an application has to register as a handler for that entity or service with the Dob. Then any application can send requests to it, as long as it knows the handler id (the "telephone number" to the handler).

Also, to be allowed to own entity instances an application has to register an entity handler for that entity type. Entity instances are the only thing that it is possible to own, and this document tries to only use "own" in that sense. Handlers are registered, not owned, entities are not owned (as opposed to entity instances), but there can be entity handlers registered, and so on.

There are quite a few different callbacks for different kinds of data, and most of them take some kind of proxy as an argument. The proxies are really only a container for a whole bunch of arguments that the user might need inside the callback, but instead of passing all the arguments separately they are collected into one proxy. This simplifies things for the application, which need only care about the parts of the proxy that it needs, and it makes it easier to add more information in a callback in the future, should there be a need to, without breaking the interfaces.

Not all methods on the proxies are applicable in all situations, for example you cannot call GetPrevious on an EntityProxy obtained in an OnNewEntity, since there is no previous version of an entity that was just created, but in OnUpdatedEntity or OnDeletedEntity calling GetPrevious will give you the version of the entity that you got in the previous subscription response for that instance.

Internally the proxies contain direct references into the Dob shared memory, which means that there are some constraints on how you can/should use them. Mainly, you’re not allowed to copy a proxy, and you’re not allowed to keep a proxy! The rationale for the second is that keeping it would also keep the data in the shared memory, which could cause the Dob to run out of shared memory, and the rationale for the first constraint is to make it more difficult to keep the proxy.

Proxies are (with a couple of exceptions) received as parameters to callbacks. After returning from the callback the shared memory that the proxy refers to is released, and the proxy therefore becomes invalid. If you try to use a proxy obtained through a callback after returning from that callback an exception will be thrown!

Of course it is possible to pass proxies to other methods, as long as the proxy is not copied. Passing it as a const-reference (const EntityProxy& proxy) works very well in C++.

[messages_sequence_diagram] shows a sequence diagram of how Dob Messages are handled.

For messages there are two different roles involved. The Message Sender sends messages and the Message Subscriber receives messages. The subscriber needs to set up the subscription, and subsequently it will receive messages in its OnMessage callback function whenever a Message Sender sends a message.

[services_sequence_diagram] contains a sequence diagram for how services are handled.

For services there are two different roles involved. The ServiceHandler is the component implementing the service and the Requestor is the component using the service. The Handler needs to register the service and then the Requestor can send requests to it.

Entities are objects that are stored in shared memory and distributed between system nodes by the Dob. It is also possible to send requests on them, to create new entities, to update or delete them. These requests are very similar to service requests, although they are tailored to be used specifically on "things" rather than services. If you haven’t read the previous section, on services, do so now, since this section assumes that you are familiar with how services and service handlers work.

[entities_sequence_diagram] shows a sequence diagram that describes (a shortened version of) the Entity Handling pattern describing how entities are handled in a Safir system.

When handling entities there are three roles involved. Entity Handler is an application registered as a handler of the entity (and is allowed to own entity instances), Entity Subscriber is an application that subscribes to the entity and Entity Requestor is an application sending a request to update the entity. At start-up Entity Subscriber sets up a subscription and Entity Handler registers an entity handler. When Entity Requestor sends a request the Dob sends it to Entity Handler. Entity Handler then validates the request, creates, updates or deletes the entity and sends a response to Entity Requestor containing the status of the request. The Entity Subscriber gets notified of the new entity.

This section will first describe "simple" entity handling, such as is shown in [entities_sequence_diagram], and later go on to describe more advanced concepts, such as persistence and injections.

First a note on application design: You are not supposed to keep internal copies of entities in your program. It is often better to use Read (see [reading_entities]) when needed. If you often need to locate a particular entity instance depending on its contents you may want to maintain some kind of lookup-table in your program, to be able to find the correct instance quickly. This is better than iterating over all instances to find the correct one.

The Dob has an area of functionality known as injections, that allows entities to be injected from an external source. The most common use for this is persistence, which is what this section describes. The purpose of persistence is to make entity instances survive an application or system restart.

This functionality is configured using the properties Safir.Dob.InjectionProperty and Safir.Dob.InjectionOverrideProperty. The possible values are:

None is the default, where nothing is remembered since the previous registration. The other values deserve their own subsections (although Injectable will not be described in this chapter, but in [systems_of_systems]).

But first a word on why they’re called synchronous; Persistence injections are known as synchronous injections since they will always occur synchronously, at application startup (or rather, when registration occurs), whereas the other kind of injection can occur asynchronously throughout the lifetime of an entity instance.

It is possible to subscribe to the registration of entity and service handlers through the SubscribeRegistration method on the Dob connection object. This is useful to be able to monitor the status of other applications in the system. E.g. is the application that handles this type of objects started and working?

The application needs a class that implements the Safir::Dob::RegistrationSubscriber consumer interface.

Then start the subscription (remember that you can do this on a service handler too!):

Note the use of ALL_HANDLERS above, that means that we’re subscribing to the registration of all handlers for the specified type, rather than a specific handler, and since we’ve also specified includeSubclasses we will also get a subscription response if a subclass of Vehicle gets registered.

When someone registers an entity handler or a service handler the Dob will notify the application of this through a call to the OnRegistered method. (Note that the function has a TypeId and HandlerId as parameters and if the implementation of the interface is used for several different classes then these can be inspected to ascertain how to handle the information).

For entity handler registration subscriptions the OnRegistered callback is called immediately when the registration is made (either when the RegisterEntity… call is made or when a pending registration is completed), not after OnInitialInjectionsDone is called. Conceptually the handler is registered before the entity instances are injected.

When a service or entity handler is unregistered the Dob will notify the application of this through a call to OnUnregistered. (A handler is unregistered when the owning application unregisters the handler or the application dies).

If a registration goes down and up “very quickly”, the subscriber is guaranteed to get first an OnUnregistered and then an OnRegistered callback. I.e. registration subscribers are guaranteed to be notified of the intermediate unregistrations, as opposed entity subscribers, who are not guaranteed to get told if an entity is deleted and then recreated immediately.

Change flags are sent unchanged from a sender to all receivers. In a received message a change flag signifies something that the sender has changed, or wants the receiver to do. A member whose change flag is not set is something that the sender does not care about.

Upon receiving an entity subscription callback the application can ask the Dob to provide change information for the entity (using GetEntityWithChangeInfo() instead of GetEntity()). If GetEntity is used all change flags will be set to false, but when GetEntityWithChangeInfo is used the Dob will set the change flags to signal what has changed since the last subscription response.

So on the first subscription response (OnNewEntity) all change flags are set to true. On subsequent subscription responses for that instance (OnUpdatedEntity) only the members that have changed are marked as changed.

Note that this is guaranteed even if the subscriber misses an intermediate state, e.g. if the subscriber misses an entity update (if the owner updates faster than the subscriber can keep up with) all members since the last update that the subscriber got will have their change flags set.

Change flags are sent unchanged from a requestor to the entity handler. In a request a change flag signifies something that the requestor wants to change in the entity.

Any member that has a change flag set is a member that the requestor wants the entity handler to set in the entity.

If a change flag is set on a member that is null that means that the requestor wants that member to be set to null. If the change flag is not set on a null member it means that the requestor does not want that member to be changed.

Change flags are sent unchanged from a requestor to the service provider. In a service request a change flag signifies something that is a part of the service request. Any member that is not changed in the request is something that the requestor does not care about.

locations.ini contains three parameters:

logging.ini has two sections, SystemLog and LowLevelLog. The LowLevelLog section contains parameters that control the logs for an internal logging and debugging facility, and you should never really need to touch these parameters, unless one of the Safir SDK Core developers have asked you to. The SystemLog section, however, contains parameters of greater interest, since they control the way Safir Logging works:

See [safir_logging] for more information on what "native" and "syslog" means, and how to use and configure the logging functionality.

typesystem.ini is a little bit more involved, so let’s start with an example:

The file contains a general section, followed by any number of [sections], each of which can be one of two kinds, a parameter override or a library module.

Since the configuration files need to be able to refer to system directories they also support environment variable expansion. E.g. $(HOME) expands to the value of the HOME environment variable.

On Windows platforms we also support the CSIDL values mentioned above, since Windows does not guarantee that there are always environment variables that correspond to them. For example the %PROGRAMDATA% environment variable is not guaranteed to be set or to point to the same directory as CSIDL_COMMON_APPDATA. So the configuration files support special variables as well as environment variables. E.g. @{SPECIAL_VARIABLE} will be expanded to the value of that variable (note that the syntax is different from the environment variable syntax).

The supported special variables are listed in [windows_special_variables]. We also provide aliases that use the Windows Known Folder naming.

Here are two more links that contain useful information about Windows paths, CSIDLs, and Windows Known Folders.: "Where Should I Write Program Data…?" and "Where Should I Store my Data and Config…?".

There is currently two special variables that are available on both Linux and Windows. They are described in [common_special_variables], below.

Safir SDK Core nodes can communicate using UDP Unicast and UDP Multicast. Multicast communication means that a single packet sent from one node can be received by multiple nodes, whereas unicast packets are only sent to one node.

For networks that support it, multicast is a lot more efficient if there are many nodes. For example an entity update can be performed using only one packet, whereas in a system using unicast one packet per node is needed. On the other hand, using multicast is not an option on all networks.

Regardless of whether multicast is used or not, all nodes must be reachable using unicast, since things that only need to be sent to one node is sent using unicast. A system can also mix nodes that are reached with multicast with nodes that are reached with unicast.

The nodes communicate with each other over two channels, the control channel and the data channel. Each of these channels is a separate stream of UDP packets over a separate set of ports.

All these things, the control and data channel ports and multicast/unicast communication, need to be configured. Some things are configured as part of each node’s Node Type, and some are configured for each individual node.

Each node in a Safir SDK Core system belongs to one and only one Node Type. Each node type has a number of parameters that control how nodes belonging to it communicate with other nodes. The node types are configured in the NodeTypes parameter in Safir.Dob.NodeParameters.dou. The parameters for each node type are listed in [node-type-parameters].

Each node has to be configured individually, to know which node type it belongs to, etc. This is done in done in the Safir.Dob.ThisNodeParameters.dou file, which therefore must be different on all nodes (or use environment variables in the parameters, as described in [environment_parameters]).

The addresses are on the format address:port, where the address can be an IP address or a DNS-resolvable address. On Linux it is also possible to specify a network interface explicitly, for example "eth0:20000", meaning use port 20000 on whatever ip address eth0 is using. On Windows there is no such feature, currently.

There is a command line utility communication_resolver that can be used to check what an address or interface name will resolv to. Use the -l flag to resolve local addresses and interfaces.

A newly started node will, as a first step, try to find and contact other nodes. The mechanism used to achieve this is called node discovery.

The second step is to either start a new system or, in case the node is in contact with nodes from an already started system, to join an existing system.

As hinted at before it is in fact possible to run multiple Dob nodes on a single computer (this is a new feature in Safir SDK Core 6.0). The way that the nodes are distinguished from each other is by setting the environment variable SAFIR_INSTANCE. All processes that have the same value of SAFIR_INSTANCE will form one node.

So, for example, you can start two instances of safir_control, one with SAFIR_INSTANCE set to 0, and one with it set to 1. When you then start an application, with SAFIR_INSTANCE set to 1 it will be part of the second safir_control instance. Remember that it is possible to specify parameter overrides that are only loaded for certain values of SAFIR_INSTANCE, as described in [typesystem_ini].

If you want the nodes to talk to each other you will need to set up seeding, as described above, but it is of course possible to run two completely separate and different systems.

One last thing, Local objects - objects that are not sent over the network.

For some entities, services and messages it is not desirable to have them sent over the network at all. These are known as local objects. Things like settings for an operator on one operator console or other things that only apply to the current node like which object is selected in the map are typically Local objects.

An object is specified as Local by mapping the Safir.Dob.DistributionScopeProperty to it, with the value "Local" as DistributionChannel, using a dom file.

A syslog message has a Priority value (PRI) that is a representation of both the Facility and the Severity of the message. PRI is used by syslog deamons to filter and redirect logs but is normally not shown in the log output. Therefore, compose the log message text so that it is clear and understandable without the facility and severity context.

The Safir Log mechanism uses facility code 1 (user-level messages) for all syslog messages and it is not a parameter visible in the interface.

The severity level must be set by the application. RFC 3164 has a brief description of the interpretation of the severity level but doesn’t really give any detailed advice. To summarize: higher severity levels imply that action from support/tech staff is more urgent, than for lower levels. In practice it isn’t always obvious what severity level to use. This is especially true for code in libraries/platforms where there usually is no knowledge of the characteristics of the calling application. One could argue that libraries should refrain from generating logs at all and instead inform the using application that an error has occurred, so that it can take appropriate action. Since Safir SDK Core does not adhere to this rule itself we leave this as something to consider during library design.

The system design in terms of redundancy might also affect the choosen severity level. For example, it might be appropriate for a system built and configured so that there is a standby application/node "taking over" in case of failure, to use severity level Error instead of Emergency for a given event.

Here are some recommendations regarding wich severity level to use for some typical classes of errors and events found in Safir systems.

Safir Log also provides a way of writing syslog messages to the Windows Event Log. To enable this, set the parameter native_logging to true.

For native logging the event source will be set to "Safir" and the severity level parameter is mapped to a corresponding Windows Event Log Type according to:

You may wonder why there isn’t any support for starting applications. The answer is that there are plans for this but as of today this is not implemented.

The application start mechanism will - when it has been implemented - provide functionality along these lines:

Stop of a specific Safir node will stop all safir-related processes in a controlled fashion. At stop, dose_main will send stop orders to all applications that have a dob connection (see [stop_orders]) which means that all application programs will be stopped as well. Note that an application might for some reason (by design or because of a bug) ignore a stop order so there is no absolute guarantee that all applications are stopped.

A Safir system stop, that is, an order to stop all nodes that constitute a Safir system, triggers a write to the “incarnation blacklist” mechanism, see [system-start].

Safir SDK Core provides a mechanism to execute an optional computer shutdown after the Safir node is stopped.

Since the command to execute a computer shutdown is tightly coupled to the operating system and also in many cases involves setting specific arguments, the actual shutdown command is specified by the parameter ShutdownCommand found in Safir.Dob.NodeParameters.

For example, /usr/bin/shutdown --poweroff now for Linux or C:\\WINDOWS\\System32\\shutdown /s /t 0 for Windows, could be used as shutdown command. The command must be given as an absolute path. Note that it might be necessary to make additional configurations outside Safir, like setting permissions, to be able to run the command.

Note that a shutdown initiated by this mechanism will implicitly execute a Safir node stop before the shutdown command, which means that the Safir programs will be stopped in a controlled fashion before the computer is shutdown.

Much like the shutdown command Safir SDK Core also provides a mechanism to reboot the computer where a safir node is running.

The reboot command is specified by the parameter RebootCommand found in Safir.Dob.NodeParameters.

Example of a reboot command for Linux: /usr/bin/shutdown --reboot now, or for Windows: C:\\WINDOWS\\System32\\shutdown /r /t 0.

The main goal of the Tracer class is for it to be as easy to use as possible, and that its usage should be as close to the languages own text input/output-syntax as possible.

There are a few different ways that the FORCE_LOG environment variable can be used.

The first is, naturally, to set the environment variable in the System Properties → Environment Variables dialog (in Windows), or in your .bashrc file (for Unix bash shell users). This has the sometimes unfortunate side effect of turning on the selected prefixes for all applications, which can be a problem if several applications use the same prefix, or if you set FORCE_LOG to "all" which will mean that all applications will log everything.

The second way is to start your program from the command line: First run set FORCE_LOG="something somethingelse" (Windows again, unix bash shell users do export FORCE_LOG=…), and then run your application from the command line. Now only your application will be run with those settings. This same way can of course be used in a script.

Lastly, if you want to run your program from the Visual Studio debugger with trace logging on by default, there is support for that too. Under Project Settings → Debugging → Environment it is possible to set environment variables. So set FORCE_LOG="all" there to get your program to start with all logging enabled. Also make sure that "Merge Environment" is set to Yes, or your program (and the libraries it depends on) will not be able to read other environment variables.

The Tracer class itself does not use the Dob in any way, it is only the TracerBackdoor that uses the Dob, which means that it is possible to use the Tracer functionality in an application that does not have a Dob connection, or to use it when the connection is not open. Of course, since this means that the TracerBackdoor cannot be used, it is not possible to use the backdoor command to control the logging. But it is still possible to use the FORCE_LOG functionality to enable logging.

The way that the Tracer works changed quite a lot with the introduction of the Safir Logging mechanism in Safir SDK Core version 4.5. The interface has only minor changes, but the behaviour behind the scenes has changed significantly.

To use the crash reporter you need to initiate it in your application. The initiation should occur as early in your program as possible.

For example, in C++ you would do something like this:

The CrashReporterStarter class is an RAII class, which means that it is equivalent to doing the following:

Java has its own crash handler, so the Crash Reporter should not be used there, and there is no interface to start it.

You also need to make sure that you build your application with debug information enabled. For example in CMake you could use the RelWithDebInfo, which produces release binaries but with debug information. When using Visual Studio you would then get a .pdb file for every .dll or .exe. Make sure to keep these .pdb files, since they are required when you’re analyzing a crash dump.

When an application crashes in a way that is caught by the crash reporter a dump file will be placed in the crash dump directory (see [locations_ini]) with a rather cryptic name (a lot of digits followed by .dmp). Apart from generating this dump file the crash reporter will attempt to log an error to the Safir Log and to standard output that a crash has happened.

If you’re using Visual Studio you can just open the .dmp file and if you’ve got all the debug information and binaries available you will then see the call stack and be able to inspect the state of the application. On Linux, you can use gdb to analyze the .dmp files, although you will have to convert the dumps to a core file using the minidump-2-core tool that can be found under src/lluf_crash_reporter.ss/src/google-breakpad/tools/. For more information about how to use the dump files please see the Google Breakpad website at http://code.google.com/p/google-breakpad/.

Letting an exception propagate out of a callback may cause your connection to the Dob to be corrupted in strange ways. You may loose messages, requests and entity subscription responses if you try to continue execution after this has occurred.

So catch all "expected" exceptions in the callbacks.

For an entity to support asynchronous injections, it must have the Safir.Dob.InjectionProperty mapped with a value of "Injectable", and the application must register it using RegisterEntityHandlerInjection and an entity handler that implements the EntityHandlerInjection consumer interface.

The EntityHandlerInjection consumer interface has, as described in [advanced_persistence], four callbacks more than the EntityHandler consumer interface: OnInjectedNewEntity, OnInjectedUpdatedEntity, OnInjectedDeletedEntity and OnInitialInjectionsDone. These are the circumstances that the callbacks are invoked (the sequence is shown in [injection_sequence_diagram]):

Note that it is not possible to tell the difference between the two kinds of calls to OnInjectedNewEntity, and in fact both new and old (i.e. persisted and injected) data can be mixed (i.e. timestamp merged) in a call to OnInjectedNewEntity.

When an application receives one of the injection callbacks it can either accept the injection, by just returning, or it can say that the injection is not complete (i.e. all deltas that are needed to make an entity that makes sense have not arrived yet) by calling IncompleteInjectionState (see [incomplete_injection_state]) or it can explicitly delete the entity. What is important to note is that if the entity is deleted is that that will cause the delete to be sent to other systems (by the injector), so delete may not be a good idea.

For injections to work correctly it is important that applications use SetChanges instead of SetAll when modifying entities. This is because SetChanges will use the change flags to work out which members should have the new and updated timestamp. In fact always prefer SetChanges to SetAll, it makes more sense w.r.t. change flags even in entities that are not injectable, and it will probably make it easier to add the possibility of handling injections at a later time to your application.

Each top-level member (note that it is only the top-level members, not members in items or individual array items) have a timestamp that is used to determine which bits of information is "newest".

Note: This fact gives constraints on the design of objects that are to be used with asynchronous injections. They will probably have to be quite "shallow".

The timestamps are based on a normal concept of time, but have an additional feature to make them better adjusted to use when the clocks on different systems (in a system of systems) "drift": When updating an entity instance the time used for timestamps is the maximum of "my own time" and "the highest time I’ve seen from other systems, plus one". This solves problems in systems with wildly diverging system times. (The timestamps can be thought of as Lamport timestamps, but with the always moving along with the UTC time, not only when there is an event.)

An example of how timestamp merges work is probably the best way to explain the algorithm:

In [ts_merge_1] an application owns an entity (and has done a single SetChanges at time 100). The entity has been reflected to other systems by the Injector.