CMX C Library

About CMX

This is CMX-c version:

For more information visit CMX on https://cern.ch/cmx and/or https://wikis.cern.ch/display/MW/CMX

Using CMX in realtime applications

The following function are realtime compatible:

• cmx_shm_get_value_single() Succeeds or directly fails with E_CMX_CONCURRENT_MODIFICATION if there is a concurrent write operation.
• cmx_shm_get_value_string() Succeeds or directly fails with E_CMX_CONCURRENT_MODIFICATION, but the time needed to read a string is much longer than for a INT/FLOAT/Bool.
• cmx_shm_set_value_single() Always succeed if there is no concurrent access to the same value.

For other functions please refer to the function documentation.

Values are referenced by so called value-handles. The validity of a value-handle cannot be ensured by the semantics of the programming language. The Developer have to be aware of the possibility that a value-handle is invalid and handle the respective error code E_CMX_INVALID_HANDLE. Particularly with regard to reading CMX SHM components that are managed by other processes.

Thread safety

All functions except cmx_shm_create(), cmx_shm_open(), cmx_shm_open_ro() and cmx_shm_create() are thread-safe.

The functions cmx_shm_create(), cmx_shm_open(), cmx_shm_open_ro() and cmx_shm_create() are only thread-safe if every function operates with a different cmx_shm_t datastructure.

Changelog

Version 2.1.0

• Moved documentation completely to doxygen (No HTML Userguide anymore)
• No change relative to 2.0.5

Version 2.0.5

• [CMW-1319] String add/remove bugfix.
• [CMW-1323] Log level INFO was wrongly mapped from C to C++
• This version is incompatible to 2.0.4 in respect to reading strings.
• Do not use this version, use 2.1.0

Version 2.0.4

• [CMW-1311] Set max. String size to 64400 Byte.
• remove limit on manifest size. Still limited by String size.
• Truncate manifest if manifest size greater than max. string size.

Version 2.0.3

• [CMW-1302] Rename namespace from CMW::CMX to cmw::cmx.

Version 2.0.2

• [CMW-1299] Add a new function `cmx_shm_open_ro()` which open the cmx shared memory structure read-only.
• [CMW-1299] Use `cmx_shm_open_ro()` for ImmutableComponent

Version 2.0.1

• _Documentation_: Improved and corrected Doxygen Documentation and Userguide. More example code.
• _Tools_: Added `cmw-cmx-dumper` tool. Make `cmw-cmx-reader` output more readable.

Version 2.0.0

• _Reduced Complexity_
  • Components are initialized with 20479 metrics by default.
  • More efficient usage of memory: Memory is not initialized until first use.
  • Components memory is backed by POSIX SHM Objects instead of SHM Segments.
  • Replacing main registry holding SHM ids with filesystem operations on /dev/shm.
• _New features_
  • Native datatypes: integer 64 bit, floating point 64 bit, bool and character strings.
  • Supports strings up to 16384 characters for each string value. The memory usage is bound to string size. -_Improved performance_: Massive performance improvement on get/set operations.
• In the CMX C++ API:
  • OO-model of the C++ API changed. See relevant section in this document.
  • No virtual methods. get/set performance equal to the C library.
  • CMX Types mapped to the C++ typesystem.
  • Possibility to turn exceptions off.
  • No need to include C-Headers of CMX while using CMX through the C++ API.

Howto use CMX

Register your process with CMX

After you have configured your compiler and linker settings (see the code examples for that), you can go into your code and start making use of CMX.

The first step is to register your process with CMX. The call `cmx_process_update()` will update (and create if necessary) a CMX Component with information about the running process.

Currently this includes the process name, hostname, manifest and some resource usage information.

 #include <cmw-cmx/process.h>
 int main(..) {
     // Create the CMX Component for the process
         cmx_process_update();
 while (1) {
     sleep(10); // do some work
         // Consider calling cmx_process_update() once in a while
             // to update the process metrics.
  cmx_process_update();
    }
    }

Register metrics

Before you can update metrics you need to assign meaningful names (see xref:naming[Naming conventions]) and register them in CMX.

 #include <cmw-cmx/shm.h>
 ...
 // Create the CMX Component
 cmx_shm * cmx_shm_ptr = cmx_shm_get(getpid(), "TestComponent");
 // assert cmx_shm_ptr != NULL

 // Add Values
 int metric_no_gets = cmx_shm_add_value_single(cmx_shm_ptr, CMX_TYPE_INT64, "no_of_gets");
 // assert ! (metric_no_gets < 0)
 int metric_no_sets = cmx_shm_add_value_single(cmx_shm_ptr, CMX_TYPE_INT64, "no_of_sets");
 // assert ! (metric_no_sets < 0)

Update metrics

We can now set or update the values of the specified metrics. The relevant timestamps (`mtime`) will be automatically updated.

 ...
 // Set Values
 cmx_shm_value value;

 value._int64 = 1234;
 cmx_shm_set_value_single(cmx_shm_ptr, metric_no_gets, CMX_TYPE_INT64, &value);
 // returns E_CMX_SUCCESS or errorcode

 value._int64 = 5678;
 cmx_shm_set_value_single(cmx_shm_ptr, metric_no_sets, CMX_TYPE_INT64, &value);
 // returns E_CMX_SUCCESS or errorcode