Arm MAP Metric Plugin Interface
Metric Plugin Interface for MAP
Metric Plugin API

The API functions available for use by a metric plugin library. More...

System Info Functions

Functions that provide information about the system or the enclosing profiler.

int allinea_get_logical_core_count (void)
 Returns the number of logical cores on this system. More...
 
int allinea_get_physical_core_count (void)
 Returns the number of physical cores on this system. More...
 
int allinea_read_config_file (const char *variable, const char *metricId, char *value, int length)
 Reads the configuration file to find the value of a variable. More...
 
const char * allinea_get_custom_data (metric_id_t metricId)
 It returns the "customData" attribute of the "source" element from the metric definition defined in the xml file. More...
 

Error Reporting Functions

Functions for reporting errors encountered by either a specific metric or an entire metric plugin library.

void allinea_set_plugin_error_message (plugin_id_t plugin_id, int error_code, const char *error_message)
 Reports an error that occurred in the plugin (group of metrics). More...
 
void allinea_set_plugin_error_messagef (plugin_id_t plugin_id, int error_code, const char *error_message,...)
 Reports an error occurred in the plugin (group of metrics). More...
 
void allinea_set_metric_error_message (metric_id_t metric_id, int error_code, const char *error_message)
 Reports an error occurred when reading a metric. More...
 
void allinea_set_metric_error_messagef (metric_id_t metric_id, int error_code, const char *error_message,...)
 Reports an error occurred when reading a metric. More...
 

Memory management functions

Async signal safe replacements for memory management functions.

Since metric library functions need to be async signal safe the standard libc memory management functions (such as malloc, free, new, delete) cannot be used. The following memory management functions can safely be used by the metric plugin libraries even if they are called from inside a signal handler.

void * allinea_safe_malloc (size_t size)
 An async-signal-safe version of malloc. More...
 
void allinea_safe_free (void *ptr)
 An async-signal-safe version of free. More...
 
void * allinea_safe_calloc (size_t nmemb, size_t size)
 An async-signal-safe version of calloc. More...
 
void * allinea_safe_realloc (void *ptr, size_t size)
 An async-signal-safe version of realloc. More...
 

Standard Utility Functions

Replacements for common libc utility functions.

Since metric library functions need to be async signal safe most standard libc functions cannot be used. In addition, even basic syscalls (such as read and write) cannot be used without risking corruption of some other metrics the enclosing profiler may be tracking (for example, bytes read or bytes written). The following functions can be safely called inside signal handlers and will accommodate I/O being done by the metric plugin without corrupting I/O metrics being tracked by the enclosing profiler.

struct timespec allinea_get_current_time (void)
 Gets the current time using the same clock as the enclosing profiler (async-signal-safe). More...
 
int allinea_safe_close (int fd)
 Closes the file descriptor fd previously opened by allinea_safe_open (async-signal-safe). More...
 
void allinea_safe_fprintf (int fd, const char *format,...)
 An async-signal-safe version of fprintf. More...
 
int allinea_safe_open (const char *file, int oflags,...)
 Opens the given file for reading or writing (async-signal-safe). More...
 
void allinea_safe_printf (const char *format,...)
 An async-signal-safe replacement for printf. More...
 
ssize_t allinea_safe_read (int fd, void *buf, size_t count)
 Reads up to count bytes from buf to fd (async-signal-safe) More...
 
ssize_t allinea_safe_read_all (int fd, void *buf, size_t count)
 Reads the entire contents of fd into buf (async-signal-safe). More...
 
ssize_t allinea_safe_read_all_with_alloc (int fd, void **buf, size_t *count)
 Reads the entire contents of fd into buf (async-signal-safe). More...
 
ssize_t allinea_safe_read_line (int fd, void *buf, size_t count)
 Reads a line from fd into buf (async-signal-safe). More...
 
void allinea_safe_vfprintf (int fd, const char *format, va_list ap)
 An async-signal-safe version of vfprintf. More...
 
ssize_t allinea_safe_write (int fd, const void *buf, size_t count)
 Writes up to count bytes from buf to fd (async-signal-safe). More...
 

Detailed Description

The API functions available for use by a metric plugin library.

Function Documentation

struct timespec allinea_get_current_time ( void  )

Gets the current time using the same clock as the enclosing profiler (async-signal-safe).

A replacement for clock_gettime that uses the enclosing profiler-preferred system clock (i.e. CLOCK_MONOTONIC).

Returns
The current time
Examples:
custom1.c.
const char* allinea_get_custom_data ( metric_id_t  metricId)

It returns the "customData" attribute of the "source" element from the metric definition defined in the xml file.

Parameters
metricIdmetric id
Returns
The custom data for the given metric id. A zero length C string if not available.
int allinea_get_logical_core_count ( void  )

Returns the number of logical cores on this system.

This count includes effective cores reported by hyperthreading.

Returns
The number of CPU cores known to the kernel (including those added by hyperthreading). -1 if this information is not available.
See also
allinea_get_physical_core_count
int allinea_get_physical_core_count ( void  )

Returns the number of physical cores on this system.

This count does not include the effective cores reported when using hyperthreading.

Returns
The number of CPU cores known to the kernel (excluding those added by hyperthreading). -1 if this information is not available
See also
allinea_get_logical_core_count
int allinea_read_config_file ( const char *  variable,
const char *  metricId,
char *  value,
int  length 
)

Reads the configuration file to find the value of a variable.

This function returns the value of a configuration variable, or an error if the file is empty, the variable is not found or the variable is improperly declared. This function must only be called from outside of the sampler (such as in allinea_plugin_initialise and similar functions) as it is not async signal safe.

Parameters
[in]variableThe name of the configuration variable.
[in]metricIdThe ID of the metric with the configuration file environment variable
[out]valueThe value of the configuration variable.
[in]lengthThe length of value
Returns
0 if there are no errors. -1 if the file name is too long. -2 if the file does not exist. -3 if the variable is not found or is improperly declared.
void* allinea_safe_calloc ( size_t  nmemb,
size_t  size 
)

An async-signal-safe version of calloc.

Allocates size * nmemb bytes and zero-initialises the memory.

To be used instead of the libc calloc.

If memory is exhausted an error is printed to stderr and the process is aborted.

Memory allocated by this function should be released by a call to allinea_safe_free(). Do not use libc free to free memory allocated by this function.

Parameters
[in]nmembthe number of bytes per element to allocate
[in]sizethe number of elements to allocate
Returns
a pointer to the start of the allocated memory region.
int allinea_safe_close ( int  fd)

Closes the file descriptor fd previously opened by allinea_safe_open (async-signal-safe).

A replacement for close. When used in conjunction with allinea_safe_read() and allinea_safe_write() the bytes read or bytes written will not be included in the enclosing profiler's I/O accounting.

Parameters
fdThe file descriptor to close.
Returns
0 on success; -1 on failure and errno set.
Examples:
custom1.c.
void allinea_safe_fprintf ( int  fd,
const char *  format,
  ... 
)

An async-signal-safe version of fprintf.

Parameters
fdThe file descriptor to write to.
formatThe format string.
...Zero or more values to be substituted into the format string in the same manner as printf.
void allinea_safe_free ( void *  ptr)

An async-signal-safe version of free.

Frees a memory region previously allocated with allinea_safe_malloc.

To be used instead of the libc free. Do not use this function to deallocate memory blocks previously allocated by the libc malloc.

Parameters
[in,out]ptrA pointer to the start of the memory region to free. This should have been previously allocated with allinea_safe_malloc(), allinea_safe_realloc(), or allinea_safe_calloc().
void* allinea_safe_malloc ( size_t  size)

An async-signal-safe version of malloc.

Allocates a memory region of size bytes. To be used instead of the libc malloc.

If memory is exhausted an error is printed to stderr and the process is aborted.

Memory allocated by this function must be released by a call to allinea_safe_free(). Do not use the libc free() to free memory allocated by this function.

Parameters
[in]sizeThe number of bytes of memory to allocate.
Returns
a pointer to the start of the allocated memory region.
int allinea_safe_open ( const char *  file,
int  oflags,
  ... 
)

Opens the given file for reading or writing (async-signal-safe).

A replacement for open. When used in conjunction with allinea_safe_read() and allinea_safe_write() the bytes read or bytes written will not be included in the enclosing profiler's I/O accounting.

Parameters
fileThe name of the file to open (may be an absolute or relative path)
oflagsFlags specifying how the file should be opened. Accepts all the flags that may be given to the libc open function i.e. O_RDONLY, O_WRONLY, or O_RDWR.
Returns
The file descriptor of the open file; -1 on failure and errno set.
Examples:
custom1.c.
void allinea_safe_printf ( const char *  format,
  ... 
)

An async-signal-safe replacement for printf.

Parameters
formatThe format string.
...Zero or more values to be substituted into the format string in the same manner as printf.
ssize_t allinea_safe_read ( int  fd,
void *  buf,
size_t  count 
)

Reads up to count bytes from buf to fd (async-signal-safe)

A replacement for read. When used in conjunction with allinea_safe_open() and allinea_safe_close(), the read bytes will be excluded from the enclosing profiler's I/O accounting.

Parameters
fdThe file descriptor to read from
bufThe buffer to read to.
countThe maximum number of bytes to read.
Returns
The number of bytes actually read; -1 on failure and errno set.
ssize_t allinea_safe_read_all ( int  fd,
void *  buf,
size_t  count 
)

Reads the entire contents of fd into buf (async-signal-safe).

When used in conjunction with allinea_safe_open() and allinea_safe_close(), the read bytes will be excluded from the enclosing profiler's I/O accounting.

Parameters
fdThe file descriptor to read from.
bufBuffer in which to copy the contents
countSize of the buffer. At most this many bytes will be written to buf.
Returns
If successful, the number of bytes read, else -1 and errno is set.
ssize_t allinea_safe_read_all_with_alloc ( int  fd,
void **  buf,
size_t *  count 
)

Reads the entire contents of fd into buf (async-signal-safe).

When used in conjunction with allinea_safe_open() and allinea_safe_close(), the read bytes will be excluded from the enclosing profiler's I/O accounting. Sufficient space for the file contents plus a terminating NUL is allocated and should be freed, using allinea_safe_free, when no longer required.

Parameters
fdThe file descriptor to read from.
bufThe pointer to when the buffer pointer should be stored.
countSize of the buffer allocated.
Returns
If successful the number of bytes read, else -1 and errno is set.
ssize_t allinea_safe_read_line ( int  fd,
void *  buf,
size_t  count 
)

Reads a line from fd into buf (async-signal-safe).

The final newline '\n' will be removed and a final '\0' added. When used in conjunction with allinea_safe_open() and allinea_safe_close(), the written bytes will be excluded from the enclosing profiler's I/O accounting.

Lines longer than count will be truncated.

Parameters
fdThe file descriptor to read from.
bufBuffer in which to copy the contents
countSize of the buffer. At most this many bytes will be written to buf.
Returns
If successful, the number of bytes read, else -1 and errno is set.
Examples:
custom1.c.
void* allinea_safe_realloc ( void *  ptr,
size_t  size 
)

An async-signal-safe version of realloc.

Reallocates a memory region if necessary, or allocates a new one if NULL is supplied for ptr.

To be used instead of the libc realloc.

If memory is exhausted an error is printed to stderr and the process is aborted.

Pointers to memory regions supplied to this function should be allocated by a call to allinea_safe_malloc(), allinea_safe_calloc() or allinea_safe_realloc().

Memory allocated by this function should be released by a call to allinea_safe_free(). Do not use libc free to free memory allocated by this function.

Parameters
[in]ptrthe starting address of the memory region to reallocate
[in]sizethe new minimum size to request
Returns
a pointer to a memory region with at least size bytes available
void allinea_safe_vfprintf ( int  fd,
const char *  format,
va_list  ap 
)

An async-signal-safe version of vfprintf.

Parameters
fdThe file descriptor to write to.
formatThe format string.
apA list of arguments for format
ssize_t allinea_safe_write ( int  fd,
const void *  buf,
size_t  count 
)

Writes up to count bytes from buf to fd (async-signal-safe).

A replacement for write When used in conjunction with allinea_safe_open() and allinea_safe_close(), the written bytes will be excluded from the enclosing profiler's I/O accounting.

Parameters
fdThe file descriptor to write to.
bufThe buffer to write from.
countThe number of bytes to write.
Returns
The number of bytes actually written; -1 on failure and errno set.
void allinea_set_metric_error_message ( metric_id_t  metric_id,
int  error_code,
const char *  error_message 
)

Reports an error occurred when reading a metric.

Parameters
metric_idThe id identifying the metric that has encountered an error. The appropriate value will have been passed in as an argument to the metric getter call.
error_codeAn error code that can be used to distinguish between the possible errors that may have occurred. The exact value is up to the plugin author but each error condition should have its own and unique error code. In the case of a failing libc function the libc errno (from <errno.h>) may be appropriate, but a plugin-author-specified constant could also be used. The meaning of the possible error codes should be documented for the benefit of users of your plugin.
error_messageA text string describing the error in a human-readable form. In the case of a failing libc function the value strerror(errno) may be appropriate, but a plugin-author-specified message could also be used.
void allinea_set_metric_error_messagef ( metric_id_t  metric_id,
int  error_code,
const char *  error_message,
  ... 
)

Reports an error occurred when reading a metric.

This method does printf-style substitutions to format values inside the error message.

Parameters
metric_idThe id identifying the metric that has encountered an error. The appropriate value will have been passed in as an argument to the metric getter call.
error_codeAn error code that can be used to distinguish between the possible errors that may have occurred. The exact value is up to the plugin author but each error condition should have its own and unique error code. In the case of a failing libc function the libc errno (from <errno.h>) may be appropriate, but a plugin-author-specified constant could also be used. The meaning of the possible error codes should be documented for the benefit of users of your plugin.
error_messageA text string describing the error in a human-readable form. In the case of a failing libc function the value strerror(errno) may be appropriate, but a plugin-author-specified message could also be used. This may include printf-style substitution characters.
...Zero or more values to be substituted into the error_message string.
Examples:
custom1.c.
void allinea_set_plugin_error_message ( plugin_id_t  plugin_id,
int  error_code,
const char *  error_message 
)

Reports an error that occurred in the plugin (group of metrics).

This method takes a plain text string as its error_message. Use allinea_set_plugin_error_messagef() instead to include specific details in the string using printf-style substitution.

This method must only be called from within allinea_plugin_initialize(), and only if the plugin library will not be able to provide its data (for example if the required interfaces are not present or supported by the system).

Parameters
plugin_idThe id identifying the plugin that has encountered an error. The appropriate value will have been passed in as an argument to the allinea_plugin_initialize() call.
error_codeAn error code that can be used to distinguish between the possible errors that may have occurred. The exact value is up to the plugin author but each error condition should have its own and unique error code. In the case of a failing libc function the libc errno (from <errno.h>) may be appropriate, but a plugin-author-specified constant could also be used. The meaning of the possible error codes should be documented for the benefit of users of your plugin.
error_messageA text string describing the error in a human-readable form. In the case of a failing libc function the value strerror(errno) may be appropriate, but a plugin-author-specified message could also be used.
void allinea_set_plugin_error_messagef ( plugin_id_t  plugin_id,
int  error_code,
const char *  error_message,
  ... 
)

Reports an error occurred in the plugin (group of metrics).

This method does printf-style substitutions to format values inside the error message.

This method must only be called from within allinea_plugin_initialize(), and only if the plugin library will not be able to provide its data (for example, if the required interfaces are not present or supported by the system).

Parameters
plugin_idThe id identifying the plugin that has encountered an error. The appropriate value will have been passed in as an argument to the allinea_plugin_initialize() call.
error_codeAn error code that can be used to distinguish between the possible errors that may have occurred. The exact value is up to the plugin author but each error condition should have its own and unique error code. In the case of a failing libc function the libc errno (from <errno.h>) may be appropriate, but a plugin-author-specified constant could also be used. The meaning of the possible error codes should be documented for the benefit of users of your plugin.
error_messageA text string describing the error in a human-readable form. In the case of a failing libc function the value strerror(errno) may be appropriate, but a plugin-author-specified message could also be used. This may include printf-style substitution characters.
...Zero or more values to be substituted into the error_message string in the same manner as printf.
Examples:
custom1.c.