Safir SDK Core User’s Guide

This document is intended to be used both as an introduction to new users of the Safir SDK Core, and as a reference for those who have used the SDK for a long time. Because of this the level of the different sections vary quite a lot. Some sections are marked as advanced (with an ^adv tag to them), to signal that they cover advanced topics that can be skipped by newcomers.

This document is a combination of several other documents, so some parts of the text have different authors, or is based on texts authored by other people.

More specifically the database section is written by Jörgen Johansson, the section on Safir.Utilities.Foreach was written by Stefan Lindström, and the appendix about the example applications was written by Petter Lönnstedt. Most of the text on the basic Dob services is based on the original Dob Software User’s Guide written by Jörgen Johansson. Mikael Wennerberg wrote the section on redundant persistency.

To obtain the latest version, please visit http://safirsdkcore.com/.

Safir SDK Core itself is available under the GPL v3 (GNU General Public License version 3) license from http://safirsdkcore.com or a commercial license from Saab AB.

The GPL license means that you are free to try out or modify the software to your hearts content and create your own applications on top of it. But you are not allowed to distribute the modified software or your applications (which will classify as derivative works) without releasing your code under the GPL license too. If you want to do this you need to obtain (and pay for…) a commercial license from Saab AB (contact information at http://www.saabgroup.com).

For more information on the GPL v3 license, see http://gplv3.fsf.org/.

Portions of the source code has other licenses and other copyright holders. These are listed in the file source package file build/packaging/debian/copyright.

Safir SDK Core is mainly aimed at providing data distribution for distributed real-time systems and information systems, but there are a few other services included in Safir SDK Core, mostly because they are needed internally. [sdk_service_summary] contains a summary of the services provided by Safir SDK Core.

Safir SDK Core consists of a number of components, some of which have cryptic four-letter acronyms as names. Each component provides one or more services. This document tries not to use the cryptic acronyms, but rather talks about the services provided, but it is good to know about them.

When we talk about the Dob what is really meant is the services provided by Dots, Dose and Dope, i.e. distributed objects with optional persistence.

Component dependencies and the layered architecture of Safir SDK Core is illustrated in [sdk_core_component_dependencies].

Again, to be able to use Safir SDK Core you do not need to understand or like these acronyms, but knowing that they are there may make some things in the SDK easier to use.

Saab sells another product Safir SDK, which is not open-source, which consists of Safir SDK Core plus a number of services that are very useful when building systems for both the civilian and military markets.

The additional services that Safir SDK provides include Alert handling, Application and Node redundancy control, communication over low-bandwidth and low connectivity media (e.g. radios of different kinds), track handling and correlation etc.

Contact Saab AB for more information (contact information at http://www.saabgroup.com).

Safir SDK Core uses the Boost library to provide low level functionality and operating system independence wrappers. See http://www.boost.org/ for more information.

Safir SDK Core also uses some other open source libraries, such as Qt for C++ widgets and CMake for building. See the build instructions for more information.

Safir SDK Core supports both the Windows and Linux platforms on the x86 and x86_64 platforms. It also successufully builds and runs on ARM Linux, but we have not tested this extensively.

Obviously it is possible to combine all these platforms into one system and use Safir SDK Core for communication (after all what use is a middleware if it isn’t platform independent).

An application should, written correctly using Boost and Safir SDK Core, be portable to all the supported platforms with no or very little effort.

The compilers that we use for building and testing for the C++ code are GNU gcc (version 4.7 or later), Microsoft Visual Studio (2010 SP1 or later). For C# code we use Visual Studio (2010 SP1 or later) or Mono (version 2.4 or later). Any Java 6 compiler should be able to compile the Java code (we’ve used Oracles’s and OpenJDK). We strive to make all our code standards compliant, so other versions and compilers should work.

There is more information about platform support on the Safir SDK Core wiki.

The Dob provides several distribution mechanisms needed to create distributed real-time systems. It is possible to interface with the Dob from several languages. Currently we provide C++, C#, and Java interfaces.

The main “selling points” include:

The Dob is appropriate for distribution of data between applications (in the same, or another, computer) in real-time and information systems, since it:

The Dob implements a distributed object cache, making it possible to either read object information synchronously from shared memory, or to subscribe to object changes.

The Dob provide services so that applications (possibly written in different languages) running on Windows and Linux platforms can communicate transparently.

The Dob provides three distribution mechanisms; Messages, Services and Entities. These three fulfil different needs in a distributed real time system, and have different characteristics and provide different guarantees.

This section describes these, and then goes on to describe how the objects are defined.

These are the simple types that class members can have, either as single members or in collections (it is also possible to put objects inside objects, which is described below).

Each member inside a Dob object has two flags associated with it. One IsNull flag and one IsChanged flag. The purpose of the IsNull flag is to allow all members to, apart from their normal values, have a state where they’re not set or unknown. The IsChanged-flag allows the Dob and applications to signal intent as well as content when transmitting data, for example indicating what has changed in an entity between two subscription responses.

All members have methods to access these flags, IsNull and IsChanged, and the flags can be manipulated using the SetChanged and SetNull methods.

The change flags are described in greater detail in [change_flags] and [interpreting_change_flags].

Apart from simple types such as integers and strings and collections of these, classes can also contain other classes. These complex types or "contained classes" are usually called Items (due to the fact that they should inherit from Safir.Dob.Item).

An Item works exactly the same way as any other Dob class apart from the fact that it is not possible to send it to another application without putting it inside an object that is distributable (i.e. a Message, Entity, Service or Response). An item has change flags and null flags just like any other member, and all of the item’s members have change flags and null flags too.

All these flags mean that there is a certain overhead to items, which in many cases is undesirable. And also, it doesn’t always make sense to have null and change flags on all members of items. For example, in a Position type, there is no point in setting the Latitude member to null. Either the position as a whole is null or it is a valid position. For this purpose Structs (inheriting from Safir.Dob.Struct) were introduced. Currently they behave exactly like an Item, but in a future Dob version they will be optimised so as to remove all the flags and overhead.

This means that there are some limitations to what you should do to a Struct. Do not use IsChanged or IsNull on any members of a struct. Instead check IsNull and IsChanged on the whole struct. Do not inherit from a user-defined struct (structs will not support inheritance). In the current Dob this will of course work, but once the optimisation is introduced your code will break.

The Dob type system supports three kinds of collections. Arrays, Sequences and Dictionaries.

An array is a fixed-length integer-indexed collection of simple or complex members. Each index has its own IsNull and IsChanged flag.

A sequence is a variable-length collection of simple or complex members. There is only an IsChanged flag on the whole collection, i.e. not on individual elements. The change flag will be set whenever a value is added, removed or replaced. There is no IsNull flag on sequences, and the IsNull operation will always return false.

A dictionary is a variable-length collection of key-value pairs. The keys can be any simple type (with some exceptions, i.e. Boolean and floating point types) and the values can be simple or complex members. Each value has its own IsNull and IsChanged flags, and the collection itself has an IsChanged flag that will be set whenever a value is added or removed.

Apart from members a class can also contain constant parameters. These parameters are not compile-time constants, instead they are read from the dou-files by the Dob when it starts and applications can ask for the values by a simple function call. This means that all that is needed to change a parameter is to change its value in the dou file, or to add a copy of the dou file, with modifications, in an override directory, as described in [typesystem_ini]) and restarting the Dob and all the applications that use the Dob (note that running the code generation, as described in [code_generation], will overwrite these changes).

Parameters are defined by a name, a type and a value. Here is an example of a parameter definition (it is cut out of its context, but it goes in the dou-file at the same level as the members-tag).

This defines a number of parameters of different types. For example the parameter MyInt32Parameter that is a 32 bit integer of value 25.

It is recommended to keep most parameters in pure parameter classes, suffixed Parameters, that inherit from Safir.Dob.Parametrization. These classes should not contain any members. The reason for this is to make it easier to know where parameters can be found. The Dob does not enforce this recommendation in any way.

String members are normally trimmed, i.e. leading and trailing whitespace is removed. This behaviour can be changed by using the attribute xml:space="preserve".

Parameter values can contain CDATA sections and use character references to specify characters by their numeric codes, e.g. Y.

Create routines allow the designer of a Dob class to define custom routines for creating commonly used instances of that class.

Create routines are similar to constructors. The members to be given as parameters to the routine, and those to be fetched from parameter definitions are defined. For example:

Will result in generated code like:

Using the CreatePosition method will allow the user to create a two-dimensional Position object using only one line of code, instead of having to first create the object, and then set the three members to correct values (Position is a Struct, so it doesn’t have the null flag for its members, hence the dummy position is used to signal that it is a two-dimensional position).

The Altitude member will be set to the value specified in the Safir.Geodesy.Position.DummyAltitude member.

The Position class also supplies a create routine for a three-dimensional position, but the two-dimensional one is a better example, since it uses a parameter.

From version 5.0 of Safir SDK Core it is also possible to write member values in place instead of referencing parameters the way it’s done above with the Altitude member. The example could then be written like this instead:

As mentioned above classes are defined by creating an Xml-file called a dou-file. The dou-file describes the class and is used to generate the interface code used by the components to interface the Dob. All dou-files have two mandatory fields that describe the name of the class and its base class. The name field contains both the name of class and the namespace the class is located in, and the baseClass field contains the base class (and its namespace) to inherit from.

In the example below the name is Vehicle and the Vehicle class is located in the namespace Vehicles which is located in the namespace Capabilities. The class is referenced by other classes as Capabilities.Vehicles.Vehicle. The Vehicle class is an Entity (that resides in the Safir.Dob namespace).

Arrays are declared by adding the field arraySize to an element or constant as shown in the example below.

Sequences are declared by adding the field sequence to an element or constant as shown in the example below.

Dictionaries are declared by adding the field dictionary to an element or constant as shown in the example below. The key type is specified using the keyType attribute.

For strings the maximum length in number of Unicode characters can be defined using the maxLength tag.

Exceeding the maxiumum string length (i.e. setting a string that is too long) will cause an exception to be thrown when the object is serialized, e.g. when a Message is transmitted. If no maximum length is specified the strings can be Very Long^TM.

The string lengths and array sizes can also be specified with parameters. The tags used for this is arraySizeRef and maxLenghtRef, and the parameter name must be fully qualified (full namespace and class name).

Of course, as mentioned in [parameters] it is recommended that parameters are placed in separate parameter classes.

It is possible - indeed it is even recommended - to add comments to most fields in dou-files since these comments will be put into the generated code in a style that is appropriate for the specific language.

A property is not an object on its own. It is merely an interface into other objects. The way that a property interfaces into an object is defined at start-up, so it is possible to change the way the interface works without recompiling any applications.

The interface itself is specified in a dou-file which is slightly different from class definitions.

The next step is to create a dom-file (has .dom as its extension) to define to which object member the property member is mapped.

The mapping above specifies that the member Name in the NamedObject property is mapped to the Callsign member of the Vehicle object.

It is also possible to map property members to values (either to direct values or to references to parameters) or to null.

It is even possible to map to members that reside inside an item array inside the mapped class.

And so on…

All fields in the property have to be mapped to something (i.e. a member, parameter or to null) to be a complete mapping. Dom-files have to be named "<mapped class name>-<property name>.dom", e.g. "Capabilties.Vehicles.Vehicle-Safir.NamedObject.dom".

It is possible to use properties on any kind of object except Structs. So the same property could be mapped into an item, an entity, a service and a response.

In order to use the classes defined by the Dou-files, interface code has to be generated for the different languages. First, source code has to be generated from the dou-files and then this source code needs to be built into loadable libraries suitable for your language and platform (e.g. dlls, shared libraries, or assemblies). Then libraries and header files have to be installed into a location where they can be accessed by your programs.

The easiest way to perform all these steps is using CMake and dobmake, for which you will need to install CMake (version 2.8 or later) and Python (version 2.7 or later).

You need to have your dou files in one or more directories, and in each directory you will need to put a file named CMakeLists.txt. This file is a CMake control file that contains the information needed to build the code in that directory (for more information on CMake, visit http://www.cmake.org).

Above is a simple CMakeLists.txt file that will build a module out of two dou files, named Dobmake.Test1.dou and Dobmake.Test2.dou. The names of the resulting binaries will be as defined in [dobmake-binaries], with <name> replaced by the value passed as the NAME argument to add_safir_generated_library. The DEPENDENCIES argument specifies that the dou file contains a dependency to the Core dou files, e.g. Safir.Dob.Entity.dou etc.

The full documentation of add_safir_generated_library can be found in the SafirSDKCoreConfig.cmake file that is installed as part of the Safir SDK Core installation package. Please read that information, since there are more things that you can do with this function than what has been described here.

If you are using cmake for your own project, you can incorporate your dou-file cmake files into your “build tree”. If you are using another build system, or are not using a build tree in cmake you will need to install the produced binaries and C++ header files somewhere where your code can find them.

Above is an example of an installation directive for the binaries and include files generated from the Test1 module. In the example the installation paths are relative, and will be relative to CMAKE_INSTALL_PREFIX (which will be set by dobmake). If you specify absolute installation paths they will be used as specified.

This section contains some pointers on how to use the generated types, and what the different operations and classes "mean".

For the examples in this section we need a couple of Dob-class definitions: B is an item (a Dob-object to use inside other objects) which contains an Int64, called MyInt. A is a Dob-Object (could be an Entity, Service, Message or Response) that contains one B, called MyB and one Float32 called MyFloat. So an A object (myA) could look like in [example_object].

Details, details, details and even more details…

Before learning about how to connect to the Dob we need to define a few basic concepts.

The first basic concept is a Consumer. A consumer is an interface, or an abstract base class, which represents a role or a set of functionality that an application can have. For example, the MessageSubscriber consumer is an interface that an application has to implement in order to be able to receive messages through a subscription.

The second basic concept is Callbacks. Each consumer has one or more callbacks, which are abstract methods that application has to implement. The MessageSubscriber consumer interface has one callback OnMessage, which is called by the Dob each time a message is received.

The third concept is Dispatching, which is the name of the strategy that the Dob uses to be able to call the callbacks. We will get to dispatching in a moment ([dispatching]), but for the moment all you need to know is that Dispatching is what causes the callbacks to be called.

For an application to talk to the Dob it needs a connection. There are in fact two kinds of connections; one that is called Connection and one that is called SecondaryConnection. In this document "connection" will be used when either kind of connection is implied, "primary connection" when Connection is referred to and "secondary connection" when a SecondaryConnection is referred to.

First we’ll describe primary connections, and we’ll cover secondary connections later in this chapter ([secondary_connections]).

To create a primary connection the application must create a Connection object and then call Open on it. The Open method takes a number of parameters:

When an application wants to close a connection it calls Close. It is not necessary to call Close before application shutdown, since the Connection destructor will do that automatically.

The three different distribution mechanisms of the Dob are used in different ways and require different things from the user application.

But before attacking the mechanisms themselves we need to talk about addressing and something called proxies.

Aspects are used to reduce the size of the Connection classes and header files, and to be able to classify peripheral or esoteric functionality as just that.

Currently there are three different aspects:

Sometimes it is not possible to handle a certain callback "right away", either due to an overflow from the Dob, or due to some external circumstance. For just this situation the Dob provides functionality to delay, or postpone, a certain callback for a certain type until some criteria is fulfilled.

Calling Postpone (can be found in the ConnectionAspectPostpone aspect) in a callback will cause the data that caused the callback to be kept (e.g. a message or request will be kept in the in-queue, or an entity subscription update will be held back) until either an overflow situation is resolved or the application calls ResumePostponed.

Note that postponed callbacks are always resumed when an overflowed queue is no longer full, so every time OnNotMessageOverflow or OnNotRequestOverflow is called an internal call to ResumePostponed is made.

A couple of examples are in place to make this clearer:

An application is required to send a request to some other application for every entity update (OnUpdatedEntity) that it receives through its entity subscription. If a lot of entities are updated "quickly" the application would soon get an overflow when sending the requests (remember that there is a limited maximum number of outstanding requests, the default is 10). The correct way of solving this (as opposed to an incorrect way, which would entail creating an infinite queue internally in the application) is to call Postpone when an overflow exception is caught. This will cause the Dob to not call OnUpdatedEntity again for any instance of the subscribed entity (and its subclasses) until the request out queue is no longer full. Once the request out queue is not full all the postponed entity updates will be received.

Another application is required to send some data to an external interface (e.g. a TCP link to some external computer/application) every time a request is received. If the external link overflows or goes down temporarily the application can no longer handle the requests, but it might be the wrong thing to just send an error response and letting the requestor handle the problem. Instead the application can call Postpone, and can then go on to handling other duties, until it detects that the external link is working again when it would call ResumePostponed, which causes the waiting requests to be dispatched (note of course that if it takes too long the request is likely to time out).

The change flags described in [change_flags] are used by the Dob distribution mechanism to ensure that components can communicate meaning as well as content. This use is slightly different in the different mechanisms. But the aim is for the change flags to mean what you would expect them to mean.

A pending registration means “I want to register this handler if there is no handler already. And if there is a handler already registered, I want to become the registerer when that one disappears.”

This functionality is to be used for applications that implement hot-standby and/or redundancy. I.e. the application is started in several nodes and if the active instance fails, another should become active instead. See [hot_standby] for more information on how to implement hot-standby and redundancy.

To be able to do pending registration you need to implement the ServiceHandlerPending or EntityHandlerPending consumer interfaces. These add an additional callback OnCompletedRegistration which is used to tell the application that it has become the registerer of a handler.

To perform the pending registration you call RegisterEntityHandlerPending or RegisterServiceHandlerPending.

The EntityHandlerPending consumer has all the Injection callbacks, since it is unlikely to want hot-standby without wanting at least SynchronousVolatile persistence.

Stop orders are used in Safir systems to allow the system to tell applications to shut down gracefully. A stop order is delivered to the application through the OnStopOrder callback on the StopHandler consumer interface that is supplied when opening a Dob connection.

The Dob will call the OnStopOrder callback when it has received a stop order for that application. These are sent by sending a DeleteRequest on the relevant instance of the Safir.Dob.ProcessInfo entity. Open Sate (see [sate]) and subscribe to Safir.Dob.ProcessInfo, find the instance that describes your application and then send a DeleteRequest on it, and your application will receive an OnStopOrder callback.

Upon receiving a stop order the application shall shut down gracefully.

When an application has several connections to the Dob, only one of them should supply a StopHandler. It is the handler of this connections responsibility to tell the other parts of the application to shut down gracefully. If several connections have stop handlers there may be race conditions, since there is no guaranteed order between which stop handler gets called first.

The basic system settings consist of three ini files: locations.ini, logging.ini, and typesystem.ini:

The system will look for these configuration files in several places, which allows them to be kept separate or together with the rest of the Safir SDK Core files. The following locations are checked, and the first configuration found will be used:

The reason for checking for the system-wide configuration before checking for a user configuration is a security measure. It will ensure that an unpriviliged user cannot insert their own configuration files, thereby modifying an installed system. If the load order was reversed an unpriviliged user could just put ini-files in his configuration directory and thereby completely change the behaviour of the system.

The Safir SDK Core installation packages will only provide system-wide configuration files. If you wish to load the configuration from the user configuration instead you will have to remove the system-wide configuration manually after installing Safir SDK Core.

A Safir SDK Core system can consist of one or more nodes running on one or more computers. This allows division of responsibility between multiple server nodes, or running HMI and business logic on different computers.

To be able to configure a networked system properly a basic understanding of how Safir SDK Core nodes communicate is needed.

The persistence service, provided by the dope_main executable has a few different features that might be good to know about. It has two backends, one that persists entities to files, and one that persists them to a database.

A few relevant parameters for the persistence service, apart from the ones described in [using_persistence].

The default behaviour is that an entity is written to external storage as soon as it is updated, which, for frequently updated entities, might generate a lot of writes to external storage.

The “Persistence Throttling” mechanism can be used to limit the number of writes for instances of a certain entity type. The throttling mechanism is applied by mapping the property Safir.Dob.PersistenceThrottlingProperty to it. An entity instance will be written no more often than given by the property value WritePeriod.

There is more information about the persistence service in [persistence_service].

Timeouts are defined using the properties Safir.Dob.RequestTimeoutProperty and Safir.Dob.RequestTimeoutOverrideProperty. If no response have been received when the timeout occurs, the Dob itself sends a timeout response to the Requestor. If the missing response arrives after this, it is just ignored. I.e., the Dob guarantees that the requestor will receive one, and only one, response. See also [request_timeouts].

The default timeout for service requests is 7 seconds and for entity requests 2 seconds, and these can be changed by changing the timeout properties on the Safir.Dob.Entity and Safir.Dob.Service classes.

Note that the RequestTimeoutProperty is inherited, whereas the RequestTimeoutOverrideProperty is not inherited, so setting a RequestTimeoutProperty on a class will cause all derived classes to get the same timeouts. The Override-property can be used when this is not the desired behaviour, or for making an exception on one level of an inheritance "tree".

By default all the length of the in and out queues of messages and requests is 10. The queue lengths can be customized by changing the parameter Safir.Dob.QueueParameters.QueueRules.

The QueueRules paramater is an array of Safir.Dob.QueueRule items, each containing one rule to apply to the queue lengths. An example is shown below.

When a new connection is opened the rules are scanned from top to bottom, and the maximum values of all rules where the ConnectionName member matches are used. No ConnectionName in a rule means "match all". It is important to have one rule, like the first one in the example above, that provide default values. Finding no match causes undefined behavior.

Here are some example connection names and their resulting queue lengths:

The Dob has two parameters that control the amount of shared memory used, one that controls the amount of memory available for the typesystem (the internal tables for all types, and all parameters), and one that controls the amount of memory available for the distribution mechanism.

The parameter that controls the typesystem memory can be found in the file typesystem.ini, as described in [typesystem_ini]. The amount of memory that the typesystem needs is completely static, i.e. it does not change at all during runtime, so if you have been able to start safir_control you know that you have enough memory allocated for the typesystem.

The parameter that controls the shared memory used by the distribution mechanism is called SharedMemorySize and can be found in Safir.Dob.NodeParameters.dou. Knowing what value to set SharedMemorySize to is trickier since the memory usage varies over time, but one approach is to run the system and monitor the memory usage, for example using dobexplorer, which is described in [dobexplorer].

This section provides some guidelines that, when applied, will help you make your application behave like a "good citizen" in the syslog ecosystem.

First of all we recommend that you establish project/product specific logging guidelines so that the separate parts that form your system exhibit a consistent logging behaviour.

Syslog is a "one-liner" oriented protocol. This, and the fact that syslog servers are known to handle messages differently regarding new lines, means that we recommend that you try to make your logs one-liners. When put together, the one-liner logs from your application should form a coherent narrative.

The configuration of Safir Logging is located in the file logging.ini (see [configuration]) and contains parameters that determine where the log messages are sent and how newlines in log messages should be handled.

Windows doesn’t have built-in support for receiving syslog messages. However, you can find third-party syslog servers that target the Windows platform, both commercial and freely distributed. One example is Kiwi Syslog Server (http://www.kiwisyslog.com), but others are available.

To enable logging using syslog on Windows, the parameter send_to_syslog_server shall be set to true and the parameters syslog_server_address and syslog_server_port shall be set to appropriate values.

The recommended configuration on Linux is to have the system configured for native logging which means that Safir Log will use the Linux system call syslog(…) for generating logs. If you want the logs sent to a remote syslog server you can configure your local sysloc daemon to forward the logs.

Most Linux distributions come with a built-in syslog deamon capable of receiving and handling syslog messages, and many distributions make it possible to switch syslog daemon, in case you are not happy with the default. Refer to the documentation of your distribution for more information.

The logging interface provided by Safir SDK Core before version 4.5 (aka Software Reporting or SwReports) is now deprecated and will be removed in some future version of the SDK. This section provides some guidelines when porting old code to use the new interface provided by Safir Log.

As already mentioned, syslog has a bias towards one-liner messages which means that it could be a good idea to try to reduce the message text to contain just the most essential information.

The following table shows the recommended mapping between the report types used by Software Reporting and syslog severity level.

To start the Node Control GUI run safir_control_gui.

In order to get system information, the GUI needs another program, safir_status. This program act as a gateway to the lower parts and exposes a Dob interface that is used by the GUI to control the nodes.

safir_control_gui communicates with the local safir_status program which means that both programs must execute on the same node. However, it is perfectly ok to start these programs on all (or a subset) of the nodes that constitue the system. The Node Control GUI on any node can be used to view the status of the complete system as well as to stop a specific node or all nodes.

[node_control_overview] shows a system with 3 nodes. In this case all three Safir nodes run on the local computer using the loopback address.

safir_control_cli is a simple command line tool that can be used to execute different stop orders. This tool doesn’t require the safir_status program to be started. Type safir_control_cli --help for the available command line options.

The Dob is started by running the executable safir_control. This program will in turn start the executable that is the real framework workhorse, dose_main.

How and when safir_control is started is outside the control of Safir SDK Core. For example, the program can be started by a script at computer start-up or manually in a terminal window.

Safir SDK Core provides functionality to stop a specific node or to stop the complete Safir system.

After a Safir node is stopped there is an option to perform a computer shutdown or reboot.

‘Stop’ is used in this description as a generic term for any of these stop mechanisms.

The SDK defines a Dob message, Safir.Application.Backdoor to be used to send debugging commands to applications. Backdoor commands can either be sent using Sate (see [sate]), or by the command-line program "bd" (use "bd -h" to get info on usage).

There are some predefined backdoor commands that applications should handle:

Backdoor commands are Dob messages and are therefore sent to all subscribers. This means that applications have to check whether or not a backdoor message is addressed to them before acting on them. The SDK provides two classes, Safir.Application.BackdoorKeeper and Safir.Application.Backdoor, that simplifies the handling of backdoor commands. The classes provide this functionality:

Output from an application as a response to a backdoor command should be through a system log, preferrably at Debug level (see [safir_logging]).

The Tracer is intended to be used for developer/integration logging inside applications. It should never be used as the sole target for logging errors, since the output can only be viewed by developers. A common way to use trace logging is to log "significant events" or other points of interest, so that the developer can find out what his component is doing when running on a test system or when running in a situation when it is not desirable or possible to halt execution with a debugger.

The interface to the trace logging functionality is a class named Safir.Application.Tracer and a class named Safir.Application.TracerBackdoor.

Tracer objects are used to send logs to the Safir Log, and the TracerBackdoor is used to turn the different Tracers on and off. The Tracer class has no Dob dependencies itself, but the TracerBackdoor uses the Backdoor functionality, as described above.

Although the Dob allows you to have several outstanding requests at a time (see also [queue_lengths]) it is sometimes desirable to be able to send off a bunch of requests and just get a summary of how it all went. Safir SDK Core provides a service for exactly this, Safir.Utilities.ForEach.

Foreach provides three Services:

For each service you can choose which type of answer you want. Immediate, Brief or Full. Immediate means that you don’t care if the operations are successful or not and you get this response immediately before all outstanding requests are finished. Brief waits for all operations to be finished before sending a response back. This information includes a summary of successful, non-successful and total operations. Full response is like Brief but you also get every single response from each operation in an array in the response.

The foreach service is provided by the "foreach" executable, which needs to be running for the foreach requests to be serviced.

For applications written in C++ and using Boost.Asio or ACE the classes Safir.Utilities.AsioDispatcher and Safir.Utilities.AceDispatcher provide Dispatcher classes that performs the thread switch and call to Dispatch as described in [dispatching].

Just instantiate the AsioDispatcher or AceDispatcher passing it your io_service or ACE_Reactor, and pass a pointer to the instance to your connection when calling Open, and you’re done. The dispatcher will now perform the thread switch through the io_service/reactor main loop using post/notify.

The ACE dispatcher is deprecated as of Safir SDK Core 6.0 and will be removed in a future release. Since it is a header-only class you can make a copy of it to your own project if you need to keep it around after it has been removed.

Under the namespace Safir.Time there are a few classes that provide functionality for obtaining the current time (both local and UTC) and converting it to and from various formats.

The time library also has support for loading an external library at runtime which could provide a higher accuracy time. The full Safir SDK provides such a library, which provides a much higher accuracy multi-node synchronised clock than NTP can provide on both GNU/Linux or Windows based systems. For more information on this, contact Saab AB (contact information at http://www.saabgroup.com).

Safir SDK Core includes a crash reporting library, google-breakpad (http://code.google.com/p/google-breakpad/). The crash reporting library can be used to generate dumps when applications crash (e.g. access violation or segmentation fault). The dumps contain, among other things, general system information, the call stack for each thread and the list of loaded modules. A dump file, together with symbolic debugging information, can be used to identify where in the software the crash occurred.

The correct way of managing overflow is to use the designated functions telling the caller when it is ok to perform the action again.

For example, if you get an overflow when sending a message (and that message should then be retried according to your application requirements/design) you can do something like this:

And then handle resending like this:

It might be tempting to use a list to keep the unsent messages in, but beware! The Dob design tries very hard to restrict queue sizes to be able to handle graceful degradation, don’t ruin it by introducing infinite queues in your application! There might be cases when a queue of a limited size may be applicable.

Note that the retry policy of your application must be part of the requirements and design of the system and your application.

Another way to handle overflows, which applies if the message or request is sent as a result of a Dob subscription or request, is to use Postpone (see [postpone]). And in the case of operator requests you probably want a tellback to ask the operator to press the button again a little bit later.

There is a little bit more info on this in [faq].

As has been mentioned in [request_timeout_config] and [service_overview] a request can result in a timeout response if the handler does not manage to handle the request in a timely fashion. It is very important to note that a timeout means that a request may still be processed!

The reason for this is that the handler may have started to process the request, but while it is being processed the timeout expires, so a timeout response is sent to the request sender. The response that the handler sends is discarded.

This means that a sender may retry sending the request, so handlers should be prepared to receive duplicate requests.

Note that this behaviour applies to both service requests and entity requests.

Since Messages, Entities, Items, and Services all inherits from Object, and it is possible to have members of the type Object, it is also possible to have Services as members in Items. And Entities as Service members etc.

There are two base classes for exceptions. Safir.Dob.Typesystem.FundamentalException and Safir.Dob.Typesystem.Exception. Exceptions should be handled by the caller, but in most situations, FundamentalExceptions should not.

In most cases a FundamentalException is to be treated as an indication that there is a programming error in your application. You should never add code that tries to handle your own programming errors. It is better if the application just dies, instead of limping along, better to detect the crash, fix and restart the application.

In some rare cases catching a FundamentalException could be justified. However, a FundamentalException of type Safir.Dob.Typesystem.SoftwareViolationException should never be handled by an application. Let it propagate up to your main loop where you report the error and exit the program.

For most applications a call to OnRevokedRegistration is completely unexpected. Unless your system uses overregistration as a feature getting this callback is a sign of an error, and the following is a recommendation on what to do in this case:

Send a Safir Log (severity Critical) that you have lost the registration. Make the report state clearly that a registration was lost, along with the type and the handler id. Then terminate the application.

The Rationale for this is that this probably happened due to a configuration error, or because someone is playing around with Sate (see [sate]), so you want to tell whoever may be interested that the system is probably not working correctly now.

The application should terminate, since it is no longer functioning correctly.

The basic rule is that an application that handles persistent entity types should wait for the callback OnIntialInjectonsDone before trying to set or delete any entity. (This callback signals that all ghosts have been injected). To get this to work the application has to distribute the "ok-to-set-entity" status to its different parts which, for some application designs, could be a hassle. An alternative in this case is to actually catch the GhostExistsException. (This is the exception you get when trying to set or delete an entity instance for which there is a ghost that hasn’t been delivered yet).

A connection can only be used from within one thread at a time. The queues and other states associated with a connection are not thread safe, for simplicity and efficiency.

Using a combination of persistence and pending registrations (see [persistence] and [pending_registrations], respectively) will let you support hot-standby and redundancy.

For an application to support redundancy the idea is that it is started in (at least) two instances, most likely on different computers in the system. At startup one is chosen as active, and the other(s) become passive. If the active instance fails (e.g. the application or the computer crashes, or the computer is shut down for maintenance) the Dob will detect that that computer has gone down, or that the application has crashed, and will tell one of the passive instances to become active.

To accomplish this, all the entities that the active instance maintained must be marked as persistent (at least volatile persistence), and one of the handlers, the "main" handler, must be registered using RegisterEntityHandlerPending.

When the OnCompletedRegistration callback is invoked for the main handler, the rest of the handlers should be registered in the normal way (using overregistration) guaranteeing that one instance of the application has registered all handlers it is supposed to.

The first time the application instances start, one of the instances will be given the registration of the main handler (through a call to OnCompletedRegistration, which will lead it to register the other handlers as well. It will then receive any persisted entities through the OnInjectedNewEntity. When this instance terminates (due to a crash or something else) the Dob will detect that and call OnCompletedRegistration on the other application instance, that will register the other handlers and receive the persisted entities. This will seamlessly cause the entity instances to move from one owner to another.

[redundancy_sequence_diagram] describes this as a sequence diagram, albeit without showing the part about registering the other handlers, since that would clutter up the diagram needlessly.

Note that applications subscribing to the entities that are redundancy-handled may see the entity instances as deleted for a short while, since in reality the handler was unregistered for a short while.

When using entities that are linked to each other through EntityId members there are a few things that you need to remember/handle in both the application that produces the entities and the applications that use them.

Applications that own the entities must make sure that no orphans are left behind, and that incorrect dangling references are avoided. An example of orphaned entites is shown in [orphan_example], where an entity uses another entity, a Location, to represent its position. If the entity is updated with a new location you must determine whether the old location is to be kept or not, to avoid cluttering the system with orphaned locations.

For applications that use the entities that contain associations you need to be aware that the Dob does not guarantee the order in which entities are delivered to subscribers, and that while you’re handling a subscription an associated entity may be removed, before you’ve managed to Read it.

There is no surefire way to handle all these cases, it must be decided on a case by case basis, but a first recommendation is to only subscribe to the "main" entities, and do Reads or temporary subscriptions to get the referred entities.

This also applies to applications that handle asynchronous injections, as described in [systems_of_systems].

An entity is configured to be Injectable using the same configuration mechanism as persistence, as described in [persistence], but using the Injectable persistence type. Entities marked as Injectable will have the behaviour of SynchronousPermanent (and thus also of SynchronousVolatile) entities, with the added functionality that injections can occur throughout the lifetime of an entity, not just at registration-time.

Asynchronous Injections are the kind of injection that can occur throughout the lifetime of an entity. The other use of injections is Persistence, as described in [persistence], can only occur at registration time.

The first thing to mention is that if a type is marked as Injectable its instances will be persisted, just as if it was marked as SynchronousPermanent. Note, however, that it is not the persistence service, dope_main, that performs the persistence in this case, but the injector, but this should be completely transparent for the user.