Function documentation
int allinea_plugin_cleanup(plugin_id_t plugin_id, void * data)
Cleans a metric plugin being unloaded. See plugin_id_t
int allinea_plugin_cleanup ( plugin_id_t plugin_id,
void * data
)
This function must be implemented by each metric plugin library. It is called when that plugin library is unloaded. Use this function to release any held resources (open files etc). Unlike most functions used in a metric plugin library, this is not called from a signal handler. Therefore, it is safe to make general function calls and even allocate or deallocate memory using the normal libc malloc/free new/delete functions.
Note
This is called after metric data has been extracted and transferred to the frontend. Therefore, you can not see plugin error messages set by allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef().
Parameters
Parameter |
Description |
|---|---|
|
Opaque handle for the metric plugin. Use this when making calls to |
|
Currently unused, is always NULL. |
Returns
0 on success; -1 on error. A description of the error must be supplied using allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef() before returning.
Examples:
Related information
int allinea_plugin_initialise(plugin_id_t plugin_id, void * data)
Initializes a metric plugin. See plugin_id_t
int allinea_plugin_initialize ( plugin_id_t plugin_id,
void * data
)
This function must be implemented by each metric plugin library. It is called when that plugin library is loaded. Use this function to setup data structures and do one-off resource checks. Unlike most functions used in a metric plugin library this is not called from a signal handler. Therefore, it is safe to make general function calls and allocate or deallocate memory using the normal libc malloc/free new/delete functions.
If it can be determined that this metric plugin cannot function, for example, the required information is not available on this machine, then it must call allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef() to explain the situation, and return -1.
Parameters
Parameter |
Description |
|---|---|
|
Opaque handle for the metric plugin. Use this when making calls to |
|
Currently unused, is always be NULL. |
Returns
0 on success; -1 on error. A description of the error must be supplied using
allinea_set_plugin_error_message() or
allinea_set_plugin_error_messagef() before returning.
Examples:
Related information
int mymetric_getDoubleValue(metric_id_t id, struct timespec * currentSampleTime, double * outValue)
Example of a floating-point metric getter function.
See metric_id_t.
int mymetric_getDoubleValue ( metric_id_t id,
struct timespec * currentSampleTime,
double * outValue
)
An example of a getter function that returns a floating point metric value. Real getter functions must be registered with the profiler using a Metric Definition File. For example, this function (if it existed) would be registered by having a <metric> element along the lines of :
1 <metric id="com.allinea.metrics.myplugin.mymetric">
2 <units>%</units>
3 <dataType>double</dataType>
4 <domain>time</domain>
5 <source ref="com.allinea.metrics.myplugin_src" functionName="mymetric_getValue"/>
6 <display>
7 <description>Human readable description</description>
8 <displayName>Human readable display name</displayName>
9 <type>instructions</type>
10 <colour>green</colour>
11 </display>
12 </metric>
The most relevant line contains functionName="mymetric_getValue". See Metric Definition File for more details on the format of this XML file.
Parameters
Direction |
Parameter |
Description |
|---|---|---|
|
|
An id used by the profiler to identify this metric. This can be used in calls to Metric plugin API functions, such as allinea_set_metric_error_message(). |
|
|
The current time. This time is acquired from a monotonic clock which reports the time elapsed from some fixed point in the past. It is unaffected by changes in the system clock. This is passed in from the profiler to avoid unnecessary calls to allinea_get_current_time(). If this metric is backfilled then this time is not the current time, instead it is the time at which the sample was taken and the time that the Linaro Forge sampler is now requesting a data point for. This parameter is additionally an In the case of a backfilled metric, |
Parameters
Direction |
Parameter |
Description |
|---|---|---|
|
|
The return value to be provided to the profiler. It is safe to assume that this pointer is not NULL. |
Returns
0 if a metric was written to outValue successfully, a non-zero value if there was an error. In the case of an error this function must call allinea_set_metric_error_message() before returning.
Caution
This function might have been called from inside a signal handler. Implementations must not make calls that are not async-signal safe. Do not use any function that implicitly or explicitly allocates or frees memory, or uses non-reentrant functions, with the exception of the memory allocators provided by the Metric plugin API (for example, allinea_safe_malloc() or allinea_safe_free()). Failure to observe async-signal safety can result in deadlocks,segfaults, or undefined/unpredictable behavior.
Note
Do not implement this function! Instead implement functions with the same signature but with a more appropriate function name.
int mymetric_getIntValue(metric_id_t id, struct timespec * currentSampleTime, uint64_t * outValue)
Example of an integer metric getter function.
See metric_id_t.
int mymetric_getIntValue ( metric_id_t id,
struct timespec * currentSampleTime,
uint64_t * outValue
)
An example of a getter function that returns an integer metric value.
Real getter functions must be registered with the profiler using a Metric Definition File. For example, this function (if it existed) would be registered by having a <metric> element along the lines of this:
1 <metric id="com.allinea.metrics.myplugin.mymetric">
2 <units>%</units>
3 <dataType>uint64_t</dataType>
4 <domain>time</domain>
5 <source ref="com.allinea.metrics.myplugin_src" functionName="mymetric_getValue"/>
6 <display>
7 <description>Human readable description</description>
8 <displayName>Human readable display name</displayName>
9 <type>instructions</type>
10 <colour>green</colour>
11 </display>
12 </metric>
The most relevant line being the one containing functionName="mymetric_getValue". See Metric Definition File for more details on the format of this XML file.
Parameters
|
|
An id used by the profiler to identify this metric. This can be used in calls to Metric plugin API functions, such as allinea_set_metric_error_message(). |
|
|
The current time. This time is acquired from a monotonic clock which reports the time elapsed from some fixed point in the past. It is unaffected by changes in the system clock. |
This is passed in from the profiler to avoid unnecessary calls to allinea_get_current_time(). If this metric is backfilled, then this time is not the current time. Instead it is the time at which the sample was taken and the time the Linaro Forge sampler is now requesting a data point for.
This parameter is additionally an out parameter and can be updated with the result from a call to allinea_get_current_time() to ensure the currentSampleTime is close to the point where the metric is read. Updating currentSampleTime from any other source is undefined.
In the case of a backfilled metric, currentSampleTime does not function as an out parameter and results in an error if it is used as such.
It is safe to assume that this pointer is not NULL.
Parameters
Direction |
Parameter |
Description |
|---|---|---|
|
|
The return value to be provided to the profiler. It is safe to assume that this pointer is not NULL. |
Returns
0 if a metric was written to outValue successfully, a non-zero value if there was an error. In the case of an error this function must call allinea_set_metric_error_message() before returning.
Warning
This function might have been called from inside a signal handler. Implementations must not make calls that are not async-signal safe. Do not use any function that implicitly or explicitly allocates or frees memory, or uses non-reentrant functions, with the exception of the memory allocators provided by the Metric plugin API (such as, allinea_safe_malloc() or allinea_safe_free()). Failure to observe async-signal safety can result in deadlocks, segfaults or undefined/unpredictable behavior.
Note
Do not implement this function, Instead implement functions with the same signature but with a more appropriate function name.
int start_profiling(plugin_id_t plugin_id)
Called when the Linaro Forge sampler is initialized. See plugin_id_t
int start_profiling ( plugin_id_t *plugin_id* )
An example of a function which is called when the Linaro Forge sampler is initialized. This callback is optional and does not need to be implemented. If this function exists it can be registered as follows.
1 <source id="com.allinea.metrics.backfill_src">
2 <sharedLibrary>libbackfill1.so</sharedLibrary>
3 <functions>
4 <start>start_profiling</start>
5 </functions>
6 </source>
This function does not need to be async-signal-safe as it is not called from a signal.
Parameters
Parameter |
Description |
|---|---|
plugin_id |
Opaque handle for the metric plugin. Use this when making calls to allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef(). |
Returns
0 on success; -1 on error. A description of the error must be supplied using allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef() before returning.
Examples:
int stop_profiling(plugin_id_t plugin_id)
Called after the Linaro Forge sampler stops sampling. See plugin_id_t.
int stop_profiling ( plugin_id_t *plugin_id* )
An example of a function which is called when the Linaro Forge sampler finishes sampling. This callback is optional and does not need to be implemented. If this function exists, it can be registered as follows:
1 <source id="com.allinea.metrics.backfill_src">
2 <sharedLibrary>libbackfill1.so</sharedLibrary>
3 <functions>
4 <start>stop_profiling</start>
5 </functions>
6 </source>
Warning
This function can be called from a signal handler, and therefore it must be async-signal-safe
Parameters
Parameter |
Description |
|---|---|
plugin_id |
Opaque handle for the metric plugin. Use this when making calls to allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef(), |
Returns
0 on success; -1 on error. A description of the error must be supplied using allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef() before returning.
Examples: