omlc_add_mp(3)

omlc_add_mp - register the definition of a new Measurement Point

omlc_add_mp registers the definition of a new Measurement Point (MP) with the OML client API and returns a handle to it. An MP accepts typed tuples as input. For most cases, it is recommended to use oml2-scaffold(1) to generate code in charge of declaring and registering MPs. This creates the oml_register_mps(3) function. The following describes how to manually declare and add MPs, much in the same way as oml_register_mps(3) does.

The definition parameter of omlc_add_mp() defines this tuple. It must be an array of OmlMPDef objects, terminated with a sentinel. Here is an example:

This definition would then be passed to omlc_add_mp() like so:

The MP must be given a name (the name parameter, "myMP" in this example), which is used to identify the source MP in the measurement output (either to the oml2-server(1) or a file). The name of each field of the tuple is the first element of the OmlMPDef object, the type is the second. The available types are described in liboml2(3).

This tuple of (name, type) pairs constitutes a declaration of what type of data will be injected into the MP, and what the data means. In this sense it is a schema or data definition for the measurement point. For more information, including an overview of how filters work and how liboml2 outputs measurements, see liboml2.conf(5).

omlc_add_mp() can only be called after omlc_init(3) has been called, and cannot be called once omlc_start(3) has been called. See liboml2(3) for more details on the phases of an OML-enabled application.

omlc_add_mp() returns NULL if an error occurs. If the call succeeds, it returns a pointer to an OmlMP object that should be used in subsequent calls to omlc_inject(3). The OmlMP pointer should be treated as an opaque handle.

omlc_add_mp() will return NULL if:

If a problem you are experiencing is not addressed in the FAQ (http://oml.mytestbed.net/projects/oml/wiki/FAQ_and_Support) nor already present in the list of know bugs (http://oml.mytestbed.net/projects/oml/issues). You could discuss it on the mailing list (details and archives at http://oml.mytestbed.net/tab/show?id=oml).

It is however advisable to open a ticket on our issue tracker at http://oml.mytestbed.net/projects/oml/issues/new. Don’t forget to include details such as client and server logs (at [--oml-log-level|-d] 2). It also helps if you can share the source code of a (minimal, if possible) example reliably triggering the problem.