Application API Guide¶

This section describes Adiak’s application interface. It is primarily routines for registering name/value pairs, and for initializing and flushing adiak data.

As previously discussed, Adiak has a C++ and a C interface. The C++ interface is wrapped in the adiak namespace. The C-interface functions are prefixed by the string adiak_.

See Concepts for an overview of important design decisions in Adiak.

Implicit routines¶

Adiak’s implicit routines register commonly used name/value pairs about a job’s execution environment under common names. The table below lists the available implicit routines, and the name/value pair they register.

Function	Name	Description
`adiakversion()`	adiakversion	Adiak library version
`user()`	user	Name of user running the job
`uid()`	uid	User ID of user running the job
`launchdate()`	launchdate	Day/time of job launch (UNIX time)
`launchday()`	launchday	Day of job launch (UNIX time)
`executable()`	executable	Executable name
`executablepath()`	executablepath	Full path to the program executable
`workdir()`	workdir	Working directory for the job
`libraries()`	libraries	Set of loaded shared libraries
`cmdline()`	cmdline	Program command line parameters
`hostname()`	hostname	Network host name
`clustername()`	clustername	Cluster name (hostname w/o numbers)
`walltime()`	walltime	Process walltime
`cputime()`	cputime	Process CPU time
`systime()`	systime	Process system time
`jobsize()`	jobsize	MPI job size
`numhosts()`	numhosts	Number of distinct nodes in MPI job
`hostlist()`	hostlist	List of distinct nodes in MPI job
`mpi_version()`	mpi_version	MPI standard version
`mpi_library()`	mpi_library	MPI_Get_library_version() output
`mpi_library_version()`	mpi_library_ vendor/version	MPI library version and vendor

The catchall function adiak_collect_all() function collects all of the common name/value pairs except walltime, systime, and cputime.

Using datatypes¶

Adiak uses a custom type system for its name/value pairs. The type system supports scalars, string-based types, and compound types like lists. In addition to basic C/C++ datatypes like integers and strings, Adiak’s type system also includes types to encode specific kinds on values like calendar dates, file paths, or program versions. See adiak_type_t for the full list of Adiak datatypes.

Each Adiak datatype also belongs to a value category like “rational”, “ordinal”, or “categorical”. This information helps tools pick appropriate visualizations for for the type, for example a bar chart vs. a line chart. The full type information is encoded in an adiak_datatype_t object, which includes the kind, value category, and (for compound types) information about the sub-type(s) and number of elements.

Users don’t usually create adiak_datatype_t objects directly, but instead use Adiak’s convenience functionality. In C, the adiak_namevalue() function uses printf-style type descriptors to specify the datatype; for example, “%d” to create an adiak_type_t::adiak_int and “%v” to create a adiak_type_t::adiak_version name/value pair. See adiak_type_t for all available typestrings. For example:

/* create an adiak_double name/value pair*/
adiak_namevalue("pi", adiak_general, NULL, "%f", 3.14159);
/* create an adiak_path name/value pair */
adiak_namevalue("input file", adiak_general, NULL, "%p", "/home/user/sim.in");

In C++, the value() template function automatically derives a suitable Adiak datatype from the given value. In addition, there are type adapters (date, version, path, and catstring) to create the special adiak types adiak_type_t::adiak_date, adiak_type_t::adiak_version, etc., from a long or string value, respectively. For example:

// create an adiak_double name/value pair
adiak::value("pi", 3.14159);
// create an adiak_path name/value pair
adiak_value("input file", adiak::path("/home/user/sim.in"));

Compound types¶

Adiak allows the creation of compound types including lists, sets, and tuples. Compound types can be recursive, so it is possible to create, for example, a list of tuples.

In the C API, the typestring for compound types uses a constructor and a subtype, for example “{%d}” for a list of ints. The value is provided via the varargs parameters for adiak_namevalue() as a C-style array followed by the data dimensions (e.g., the array length). Recursive type definitions use multiple dimension parameters, specified in order from the outermost to the innermost type. For example:

/* create a set of ints */
int squares[4] = { 1, 4, 9, 16 };
adiak_namevalue("squares", adiak_general, NULL, "[%d]", squares, 4);

/* create a (int,string,path) tuple */
struct tuple_t {
   int i; char* s; char* p;
} t = {
   1, "a", "/home/usr"
};
adiak_namevalue("mytuple", adiak_general, NULL, "(%d,%s,%p)", &t, 3);

/* create a list of (int,string) tuples */
struct int_string_t { int i; char* s; };
int_string_t hello[3] = { { 1, "hello" }, { 2, "adiak" }, { 3, "!" } };
adiak_namevalue("hello", adiak_general, NULL, "{(%d,%s)}", hello, 3, 2);

In the C++ API, the value() template function creates compound types when given specific STL containers as value, e.g. std::tuple for tuples or std::vector for lists. For example:

// create a set of ints
std::set<int> squares { 1, 4, 9, 16 };
adiak::value("squares", squares);

// create a (int,string,path) tuple
std::tuple<int,std::string,adiak::path> t { 1, "a", adiak::path("/home/usr") };
adiak::value("mytuple", t);

// create a list of (int,string) tuples
std::vector<std::tuple<int,std::string>> hello { { 1, "hello" }, { 2, "adiak" }, { 3, "!" } };
adiak::value("hello", hello);

For detailed information on how to create each compound type, refer to the adiak_type_t documentation.

Reference values¶

Optionally, values can be stored as references, where Adiak does not copy the data but only keeps a pointer to it. Reference entries are available for string types and compound types (lists, sets, etc.). Scalar types (int, double, etc.) cannot be stored as references.

Any objects stored as references must be retained in memory by the application throughout the lifetime of the program or until adiak_clean() is called.

Currently, reference values must be created through the C API. To do so, place a & in front of the type specifier in adiak_namevalue(), e.g. &{%d} for a list of integers or &%s for a string. For compound types, the & can be applied to an inner type to create a shallow copy, e.g. {&%s} for a shallow-copy list of zero-copy strings. Examples:

static const int array[9] = { -1, 2, -3, 4, 5, 4, 3, 2, 1 };
static const char* string_a = "A long string";
static const char* string_b = "Another long string";

struct int_string_tuple {
    long long i; const char* str;
};
static const struct int_string_tuple data[3] = {
    { 1, "Hello" }, { 2, "Adiak" }, { 3, "!" }
};

/* A zero-copy list of ints */
adiak_namevalue("array", adiak_general, NULL, "&{%d}", array, 9);
/* A zero-copy string */
adiak_namevalue("string", adiak_general, NULL, "&%s", string_a);
/* A set of zero-copy strings (shallow-copies the list but not the strings)*/
const char* strings[2] = { string_a, string_b };
adiak_namevalue("set_of_strings", adiak_general, NULL, "[&%s]", strings, 2);
/* A full deep copy list of tuples */
adiak_namevalue("data_deepcopy", adiak_general, NULL, "{(%lld,%s)}", hello_data, 3, 2);
/* A zero-copy list of tuples */
adiak_namevalue("data_ref_0", adiak_general, NULL, "&{(%lld,%s)}", hello_data, 3, 2);
/* A shallow-copy list of zero-copy tuples */
adiak_namevalue("data_ref_1", adiak_general, NULL, "{&(%lld,%s)}", hello_data, 3, 2);
/* A shallow-copy list of tuples with zero-copy strings */
adiak_namevalue("data_ref_2", adiak_general, NULL, "{(%lld,&%s)}", hello_data, 3, 2);

API reference¶

group UserAPI

Adiak API for registering name/value pairs.

Data type representation

enum adiak_numerical_t¶

Describes value category of an Adiak datatype.

Values:

enumerator adiak_numerical_unset¶

enumerator adiak_categorical¶: Means values are unique

enumerator adiak_ordinal¶: Means the value has an ordering

enumerator adiak_interval¶: Means the value has ranges (can be subtracted)

enumerator adiak_rational¶: Means the value is divisible

enum adiak_type_t¶

Adiak datatype descriptor.

The “typestring” values shown below are the printf-style type descriptors that must be passed as the typestr argument in adiak_namevalue for values of the corresponding type.

Type	Typestring	Value category
adiak_long	“%ld”	rational
adiak_ulong	“%lu”	rational
adiak_int	“%d”	rational
adiak_uint	“%u”	rational
adiak_double	“%f”	rational
adiak_date	“%D”	interval
adiak_timeval	“%t”	interval
adiak_version	“%v”	ordinal
adiak_string	“%s”	ordinal
adiak_catstring	“%r”	categorical
adiak_path	“%p”	categorical
adiak_range	“<subtype>”	categorical
adiak_set	“[subtype]”	categorical
adiak_list	“{subtype}”	categorical
adiak_tuple	“(t1,t2,..)”	categorical
adiak_longlong	“%lld”	rational
adiak_ulonglong	“%llu”	rational

Values:

enumerator adiak_type_unset¶: A placeholder for uninitialized types.

enumerator adiak_long¶: A C long.

enumerator adiak_ulong¶: A C unsigned long

enumerator adiak_int¶: A C int.

enumerator adiak_uint¶: A C unsigned int

enumerator adiak_double¶: A C double.

enumerator adiak_date¶: A date. Passed as a signed long in seconds since epoch.

enumerator adiak_timeval¶: A time interval. Passed as a struct timeval*

enumerator adiak_version¶: A program version number. Passed as char*.

enumerator adiak_string¶

enumerator adiak_catstring¶: A categorical (i.e., unordered) string. Passed as char*.

enumerator adiak_path¶: A file path. Passed as char*.

enumerator adiak_range¶

A compound type representing a range of values.

Another typestring should be passed between the “< >” arrow brackets, e.g. “<%d>” for an interval of ints.

The values passed to the C API should be passed as two values v1 and v2 representing the range [v1, v2). In the C++ interface, use the overloaded adiak::value() function that takes two value parameters.

enumerator adiak_set¶

A compound type representing a set of values.

The set is unordered and should not contain duplicates. Another typestring should be passed between the “[ ]” square brackets, e.g. “[%u]” for a set of uints. The values passed to the C interface should be a C-style array of the subtype and a size integer.

The value passed to the C++ interface should be a std::set with the subtype.

enumerator adiak_list¶

A compound type representing a list of values.

The list order is preserved. Another typestring should be passed between the “{ }” braces, e.g. “{%s}” for a list of strings. The values passed to the C interface should be a C-style array of the subtype and a size integer.

The value passed to the C++ interface should be a std::vector or a std::list with the subtype.

enumerator adiak_tuple¶

A compound type representing a tuple.

N typestrings should be passed between the “( )” parentheses, e.g. “(%d,%s,%p)” for a (int,string,path) tuple. In the C interface, the values should be passed as a pointer to a C struct with the tuple values and an int with the number of tuple elements.

In the C++ interface, the value should be a std::tuple with N elements.

enumerator adiak_longlong¶: A C long long

enumerator adiak_ulonglong¶: A C unsigned long long

typedef int adiak_category_t¶

typedef struct adiak_datatype_t adiak_datatype_t¶

Adiak datatype specification.

This specification contains the datatype’s descriptor, category, and (for compound types) its potentially recursive sub-types.

typedef union adiak_value_t adiak_value_t¶

Adiak value union.

The adiak_value_t union contains the value part of a name/value pair. It is used with an adiak_datatype_t, which describes how to interpret the value. The following table describes what union value should be read for each adiak_type_t:

Type	Union value
adiak_long	v_long
adiak_ulong	v_long (cast to unsigned long)
adiak_int	v_int
adiak_uint	v_int (cast to unsigned int)
adiak_double	v_double
adiak_date	v_long (as seconds since epoch)
adiak_timeval	v_ptr (cast to struct timeval*)
adiak_version	v_ptr (cast to char*)
adiak_string	v_ptr (cast to char*)
adiak_catstring	v_ptr (cast to char*)
adiak_path	v_ptr (cast to char*)
adiak_range	v_subval (as adiak_value_t[2]) [*]
adiak_set	v_subval (as adiak_value_t array) [*]
adiak_list	v_subval (as adiak_value_t array) [*]
adiak_tuple	v_subval (as adiak_value_t array) [*]
adiak_longlong	v_longlong
adiak_ulonglong	v_longlong (as unsigned long long)

[*] Reference (zero-copy) container types store the original input pointer in v_ptr.

static const adiak_datatype_t adiak_unset_datatype = {adiak_type_unset, adiak_numerical_unset, 0, 0, NULL, 0, 0}¶

adiak_category_unset¶: Adiak category unset.

adiak_category_all¶: Any Adiak category (for use in tool API)

adiak_general¶: Adiak category for general information about runs.

adiak_performance¶: Adiak category for information about performance.

adiak_control¶: Adiak category for control and meta commands (e.g., flush)

C user API

void adiak_init(void *mpi_communicator_p)¶

Initializes the Adiak interface.

Must be called by the application before registering name/value pairs.

In an MPI job, adiak_init takes a pointer to an MPI communicator. MPI_COMM_WORLD would typically be the correct communicator to pass. The init routine should be called after MPI_Init has completed from each rank in the MPI job.

This routine can safely be called multiple times. Subsequent calls have no effect.

Parameters: mpi_communicator_p – Pointer to an MPI communicator, cast to void*. NULL if running without MPI.

void adiak_fini()¶

Finalizes the Adiak interface.

adiak_fini should be called before program exit. In an MPI job, it should be called before MPI_finalize.

int adiak_namevalue(const char *name, int category, const char *subcategory, const char *typestr, ...)¶

Register a name/value pair with Adiak.

Values are associated with the specified name and described by the specified type. The printf-style typestr describes the type of the value, which is constructed from the string specifiers shown in adiak_type_t. The varargs contain the value and, if needed, any additional parameters for the type (e.g., list length).

Examples:

adiak_namevalue("numrecords", adiak_general, NULL, "%d", 10);

adiak_namevalue("buildcompiler", adiak_general, "build data", "%v", "gcc@4.7.3");

double gridvalues[] = { 5.4, 18.1, 24.0, 92.8 };
adiak_namevalue("gridvals", adiak_general, NULL, "[%f]", gridvalues, 4);

struct { int pos; const char *val; } letters[3] = { {1, "a"}, {2, "b"}, {3, "c"} };
adiak_namevalue("alphabet", adiak_general, NULL, "[(%d, %s)]", letters, 3, 2);

By default, Adiak makes deep copies of the provided names and values, so it is safe to free the provided objects. Optionally, one can prefix the type specifier with & to create a reference entry where Adiak does not copy the data but only stores the provided pointer. In this case, the data objects must be retained until program exit or until adiak_clean is called.

Only string or compound/container types (list, set, etc.) can be stored as references. For compound types, the & can be applied to an inner type to create a shallow copy, e.g. {&s} for a shallow-copy list of zero-copy strings.

Examples:

static const char* strings[2] = { "A string", "Another string" };

// zero-copy string
adiak_namevalue("string", adiak_general, NULL, "&%s", strings[0]);
// deep-copy list of strings
adiak_namevalue("list_0", adiak_general, NULL, "{%s}", strings);
// zero-copy list of strings
adiak_namevalue("list_1", adiak_general, NULL, "&{%s}", strings);
const char* reverse[2] = { strings[1], strings[0] };
// shallow-copy list of zero-copy strings
adiak_namevalue("list_2", adiak_general, NULL, "{&%s}", reverse);

There is also a convenient C++ interface for registering values, see adiak::value.

Parameters

name – Name of the Adiak name/value pair. Adiak makes a copy of the string, and memory associated with it can be freed after this call completes.
category – Describes how the name/value pair should be categorized. Tools can subscribe to a set of categories. Users can use Adiak-provided categories like adiak_general, adiak_performance, etc. or create their own. Values <=1000 are reserved for Adiak. User-defined categories must have a value >1000. The adiak_general category is a good default value.
subcategory – An optional user-defined category string that is passed to underlying tools. Can be NULL.
typestr – A printf-style type string describing the datatype of the value. As example, the typestr could be “%d”, “%s”, or “[%p]” to describe an integer, string, or set-of-paths value, respectively. See adiak_type_t.
... – The value of the name/value pair. It is interpreted based on the typestr. For scalars and strings, this is typically just the value itself. Compound types like arrays or tuples require additional parameters like an array length. See adiak_type_t to learn how to encode the value for each Adiak datatype.

Returns

On success, returns 0. On a failure, returns -1.

adiak_datatype_t *adiak_new_datatype(const char *typestr, ...)¶: Constructs a new adiak_datatype_t that can be passed to adiak_raw_namevalue.

Note

It is not safe to free this datatype.

int adiak_raw_namevalue(const char *name, int category, const char *subcategory, adiak_value_t *value, adiak_datatype_t *type)¶: Register a new name/value pair with Adiak, but with an already constructed datatype and value.

int adiak_adiakversion()¶: Makes a ‘adiakversion’ name/val with the Adiak library version.

int adiak_user()¶: Makes a ‘user’ name/val with the real name of who’s running the job.

int adiak_uid()¶: Makes a ‘uid’ name/val with the uid of who’s running the job.

int adiak_launchdate()¶: Makes a ‘launchdate’ name/val with the seconds since UNIX epoch of when this job started.

int adiak_launchday()¶

Makes a ‘launchday’ name/val with the date when this job started, but truncated to midnight.

Creates an adiak_date value named “launchday” of the time when this process was started, in the form of seconds since UNIX epoch, but rounded down to the previous midnight at GMT+0. This can be used to group jobs that ran on the same day.

int adiak_executable()¶: Makes an ‘executable’ name/val with the executable file for this job.

int adiak_executablepath()¶: Makes an ‘executablepath’ name/value with the full executable file path.

int adiak_workdir()¶: Makes a ‘working_directory’ name/val with the cwd for this job.

int adiak_libraries()¶: Makes a ‘libraries’ name/value with the set of shared library paths.

int adiak_cmdline()¶: Makes a ‘cmdline’ name/val string set with the command line parameters.

int adiak_hostname()¶: Makes a ‘hostname’ name/val with the hostname.

int adiak_clustername()¶: Makes a ‘cluster’ name/val with the cluster name (hostname with numbers stripped)

int adiak_walltime()¶: Makes a ‘walltime’ name/val with the walltime how long this job ran.

int adiak_systime()¶: Makes a ‘systime’ name/val with the timeval of how much time was spent in IO.

int adiak_cputime()¶: Makes a ‘cputime’ name/val with the timeval of how much time was spent on the CPU.

int adiak_job_size()¶: Makes a ‘jobsize’ name/val with the number of ranks in an MPI job.

int adiak_hostlist()¶

Makes a ‘hostlist’ name/val with the set of hostnames in this MPI job.

This function invokes MPI collective operations and must be called by all MPI ranks in the communicator provided to adiak_init.

int adiak_num_hosts()¶

Makes a ‘numhosts’ name/val with the number of hosts in this MPI job.

This function invokes MPI collective operations and must be called by all MPI ranks in the communicator provided to adiak_init.

int adiak_mpi_version()¶: Makes a ‘mpi_version’ name/val with the MPI standard version.

int adiak_mpi_library()¶

Makes a ‘mpi_library’ name/val with MPI library info.

Returns the information given by MPI_Get_library_version(). The output is different for each MPI library implementation, and can be a long, multi-line string.

int adiak_mpi_library_version()¶

Reports MPI library version and vendor information.

Makes mpi_library_version and mpi_library_vendor name/value pairs with the MPI library version and vendor. It parses out the version and vendor information from the string provided by MPI_Get_library_version(). Currently this works for CRAY MPICH, IBM Spectrum MPI, Open MPI, MVAPICH2, and MPICH.

int adiak_collect_all()¶

Collect all available built-in Adiak name/value pairs.

This shortcut invokes all of the pre-defined routines that collect common metadata (like adiak_uid, adiak_launchdate, etc).

If MPI support is enabled then this function is a collective all and must be called by all MPI ranks in the communicator provided to adiak_init.

Returns: -1 if no data could be collected, otherwise 0.

int adiak_flush(const char *location)¶: Trigger a flush in registered tools.

int adiak_clean()¶

Clear all adiak name/values.

This routine frees all heap memory used by adiak. This includes the cache of all name/value pairs passed to Adiak. After this call completes, adiak will report it has no name/value pairs. Adiak should not be used again after this call completes.

adiak_numerical_t adiak_numerical_from_type(adiak_type_t dtype)¶: Return the value category for dtype.

C++ user API

inline void init(void *mpi_communicator_p)¶

Initializes the Adiak interface.

Must be called by the application before registering name/value pairs.

In an MPI job, adiak_init takes a pointer to an MPI communicator. MPI_COMM_WORLD would typically be the correct communicator to pass. The init routine should be called after MPI_Init has completed from each rank in the MPI job.

This routine can safely be called multiple times. Subsequent calls have no effect.

Parameters: mpi_communicator_p – Pointer to an MPI communicator, cast to void*. NULL if running without MPI.

inline void fini()¶

Finalizes the Adiak interface.

adiak_fini should be called before program exit. In an MPI job, it should be called before MPI_finalize.

template<typename T> bool value(std::string name, T value, int category = adiak_general, std::string subcategory = "")¶

Register a name/value pair with Adiak.

Adiak will make a shallow copy of the object and pass its name/value/type to any underlying subscribers (which register via adiak_tool.h). adiak::value returns true if it completes successfully, or false on an error.

For the value, you can pass in:

single objects
An STL container (which will pass through as a set of objects)
A pair of objects, A and B, which represents a range [A, B)

For the underlying type, Adiak understands:

Integral objects (int, long, double and signed/unsigned)
Strings
UNIX time objects (struct timeval pointers)
Dates, as seconds since epcoh*
version numbers*
paths*

Special types like paths and versions should be passed in as strings and longs using the adiak::date/version/path wrappers below so they’re distinguishable.

You can pass in other types of objects, or build a custom adiak_datatype_t, but the underlying subscribers may-or-may-not know how to interpret your underlying object.

You can optionally also pass a category field, which can help subscribers categorize data and decide what to respond to.

Examples:

adiak::value("maxtempature", 70.2);

adiak::value("compiler", adiak::version("gcc@8.1.0"));

struct timeval starttime = ...;
struct timeval endtime = ...;
adiak::value("runtime", starttime, endtime, adiak_performance);

std::set<std::string> names;
names.insert("matt");
names.insert("david");
names.insert("greg");
adiak::value("users", names);

See also

adiak_namevalue

Parameters

name – The name of the Adiak name/value
value – The value of the Adiak name/value
category – An Adiak category like adiak_general or adiak_performance. If in doubt, use adiak_general.
subcategory – An optional user-defined subcategory

template<typename T> bool value(std::string name, T valuea, T valueb, int category = adiak_general, std::string subcategory = "")¶

inline bool adiakversion()¶: Makes a ‘adiakversion’ name/val with the Adiak library version.

inline bool user()¶: Makes a ‘user’ name/val with the real name of who’s running the job.

inline bool uid()¶: Makes a ‘uid’ name/val with the uid of who’s running the job.

inline bool launchdate()¶: Makes a ‘launchdate’ name/val with the seconds since UNIX epoch of when this job started.

inline bool launchday()¶

Makes a ‘launchday’ name/val with the date when this job started, but truncated to midnight.

Creates an adiak_date value named “launchday” of the time when this process was started, in the form of seconds since UNIX epoch, but rounded down to the previous midnight at GMT+0. This can be used to group jobs that ran on the same day.

inline bool executable()¶: Makes an ‘executable’ name/val with the executable file for this job.

inline bool executablepath()¶: Makes an ‘executablepath’ name/value with the full executable file path.

inline bool workdir()¶: Makes a ‘working_directory’ name/val with the cwd for this job.

inline bool libraries()¶: Makes a ‘libraries’ name/value with the set of shared library paths.

inline bool cmdline()¶: Makes a ‘cmdline’ name/val string set with the command line parameters.

inline bool hostname()¶: Makes a ‘hostname’ name/val with the hostname.

inline bool clustername()¶: Makes a ‘cluster’ name/val with the cluster name (hostname with numbers stripped)

inline bool walltime()¶: Makes a ‘walltime’ name/val with the walltime how long this job ran.

inline bool systime()¶: Makes a ‘systime’ name/val with the timeval of how much time was spent in IO.

inline bool cputime()¶: Makes a ‘cputime’ name/val with the timeval of how much time was spent on the CPU.

inline bool jobsize()¶: Makes a ‘jobsize’ name/val with the number of ranks in an MPI job.

inline bool hostlist()¶

Makes a ‘hostlist’ name/val with the set of hostnames in this MPI job.

This function invokes MPI collective operations and must be called by all MPI ranks in the communicator provided to adiak_init.

inline bool numhosts()¶

Makes a ‘numhosts’ name/val with the number of hosts in this MPI job.

This function invokes MPI collective operations and must be called by all MPI ranks in the communicator provided to adiak_init.

inline bool mpi_version()¶: Makes a ‘mpi_version’ name/val with the MPI standard version.

inline bool mpi_library()¶

Makes a ‘mpi_library’ name/val with MPI library info.

Returns the information given by MPI_Get_library_version(). The output is different for each MPI library implementation, and can be a long, multi-line string.

inline bool mpi_library_version()¶

Reports MPI library version and vendor information.

Makes mpi_library_version and mpi_library_vendor name/value pairs with the MPI library version and vendor. It parses out the version and vendor information from the string provided by MPI_Get_library_version(). Currently this works for CRAY MPICH, IBM Spectrum MPI, Open MPI, MVAPICH2, and MPICH.

inline bool flush(std::string output)¶: Trigger a flush in registered tools.

inline bool clean()¶

Clear all adiak name/values.

This routine frees all heap memory used by adiak. This includes the cache of all name/value pairs passed to Adiak. After this call completes, adiak will report it has no name/value pairs. Adiak should not be used again after this call completes.

inline bool collect_all()¶

Collect all available built-in Adiak name/value pairs.

This shortcut invokes all of the pre-defined routines that collect common metadata (like adiak_uid, adiak_launchdate, etc).

If MPI support is enabled then this function is a collective all and must be called by all MPI ranks in the communicator provided to adiak_init.

Returns: -1 if no data could be collected, otherwise 0.

struct adiak_datatype_t

#include <include/adiak.h>

Adiak datatype specification.

This specification contains the datatype’s descriptor, category, and (for compound types) its potentially recursive sub-types.

Public Members

adiak_type_t dtype¶: Type descriptor.

adiak_numerical_t numerical¶: Value category of this datatype.

int num_elements¶

Number of elements for container types (e.g., number of list elements).

This is the number of sub-elements if the container is a Adiak-created copy (which is the default). The number of sub-elements of reference (zero copy) containers is in num_ref_elements.

int num_subtypes¶

Number of sub-types.

Should be N for tuples, 1 for other container types, and 0 for basic types.

struct adiak_datatype_t **subtype¶: List of subtypes of container types. NULL for other types.

int is_reference¶: 1 if this a reference (i.e., zero-copy) entry, 0 if not

int num_ref_elements¶: Number of sub-elements for reference container values.

union adiak_value_t

#include <include/adiak.h>

Adiak value union.

The adiak_value_t union contains the value part of a name/value pair. It is used with an adiak_datatype_t, which describes how to interpret the value. The following table describes what union value should be read for each adiak_type_t:

Type	Union value
adiak_long	v_long
adiak_ulong	v_long (cast to unsigned long)
adiak_int	v_int
adiak_uint	v_int (cast to unsigned int)
adiak_double	v_double
adiak_date	v_long (as seconds since epoch)
adiak_timeval	v_ptr (cast to struct timeval*)
adiak_version	v_ptr (cast to char*)
adiak_string	v_ptr (cast to char*)
adiak_catstring	v_ptr (cast to char*)
adiak_path	v_ptr (cast to char*)
adiak_range	v_subval (as adiak_value_t[2]) [*]
adiak_set	v_subval (as adiak_value_t array) [*]
adiak_list	v_subval (as adiak_value_t array) [*]
adiak_tuple	v_subval (as adiak_value_t array) [*]
adiak_longlong	v_longlong
adiak_ulonglong	v_longlong (as unsigned long long)

[*] Reference (zero-copy) container types store the original input pointer in v_ptr.

Public Members

signed long v_long¶

int v_int¶

short v_short¶

char v_char¶

double v_double¶

void *v_ptr¶

union adiak_value_t *v_subval¶

long long v_longlong¶

struct date¶: #include <include/adiak.hpp>

Convert an unsigned long into a adiak_date.

struct version¶

#include <include/adiak.hpp>

Convert a string into a adiak_version.

Example:

adiak::value("version", adiak::version("1.2.3beta4"));

struct path¶

#include <include/adiak.hpp>

Convert a string into a adiak_path.

Example:

adiak::value("input deck", adiak::path("/home/user/sim.in"));

struct catstring¶

#include <include/adiak.hpp>

Convert a string into a adiak_catstring.

Example:

adiak::value("testcase", adiak::catstring("x1_large"));

Application API Guide¶

Implicit routines¶

Using datatypes¶

Compound types¶

Reference values¶

API reference¶

Table of Contents

Previous topic

Next topic

This Page