hw.h File Reference

#include <stdbool.h>
#include <adaptyst/amod_t.h>

Go to the source code of this file.

Classes
struct	option
struct	profile_info

Macros
#define	ADAPTYST_OK   0
#define	ADAPTYST_ERR_MODULE_NOT_FOUND   1
#define	ADAPTYST_ERR_OUT_OF_MEMORY   2
#define	ADAPTYST_ERR_EXCEPTION   3
#define	ADAPTYST_ERR_TERMINAL_NOT_INITIALISED   4
#define	ADAPTYST_ERR_LOG_DIR_CREATE   5
#define	ADAPTYST_ERR_INIT_ONLY   6
#define	ADAPTYST_ERR_TIMEOUT   7
#define	ADAPTYST_ERR_WORKFLOW_NOT_STARTED   8
#define	ADAPTYST_ERR_TIMESTAMP   9
#define	ADAPTYST_ERR_WORKFLOW_RUNNING   10

Enumerations
enum	option_type {   INT = 1 , STRING = 2 , UNSIGNED_INT = 3 , BOOL = 4 ,   NONE = 0 }
enum	profile_type { LINUX_PROCESS = 0 }

Functions
const char *	adaptyst_get_library_dir (amod_t id)
option *	adaptyst_get_option (amod_t id, const char *key)
bool	adaptyst_set_error (amod_t id, const char *msg)
const char *	adaptyst_get_log_dir (amod_t id)
bool	adaptyst_send_data (amod_t id, char *buf, unsigned int n)
bool	adaptyst_receive_data (amod_t id, char *buf, unsigned int buf_size, int *n)
bool	adaptyst_receive_data_timeout (amod_t id, char *buf, unsigned int buf_size, int *n, long timeout_seconds)
bool	adaptyst_send_string (amod_t id, const char *str)
bool	adaptyst_receive_string (amod_t id, const char **str)
bool	adaptyst_receive_string_timeout (amod_t id, const char **str, long timeout_seconds)
const char *	adaptyst_get_node_name (amod_t id)
bool	adaptyst_log (amod_t id, const char *msg, const char *type)
bool	adaptyst_print (amod_t id, const char *msg, bool sub, bool error, const char *type)
const char *	adaptyst_get_module_dir (amod_t id)
profile_info *	adaptyst_get_profile_info (amod_t id)
bool	adaptyst_set_profile_info (amod_t id, profile_info *info)
bool	adaptyst_is_directing_node (amod_t id)
bool	adaptyst_profile_notify (amod_t id)
int	adaptyst_profile_wait (amod_t id)
bool	adaptyst_process_src_paths (amod_t id, const char **paths, int n)
const char *	adaptyst_get_cpu_mask (amod_t id)
const char *	adaptyst_get_tmp_dir (amod_t id)
const char *	adaptyst_get_local_config_dir (amod_t id)
bool	adaptyst_set_will_profile (amod_t id, bool will_profile)
bool	adaptyst_has_in_tag (amod_t id, const char *tag)
bool	adaptyst_has_out_tag (amod_t id, const char *tag)
int	adaptyst_get_internal_error_code (amod_t id)
const char *	adaptyst_get_internal_error_msg (amod_t id)
unsigned long long	adaptyst_get_timestamp (amod_t id)
unsigned long long	adaptyst_get_workflow_start_time (amod_t id)
unsigned long long	adaptyst_get_workflow_end_time (amod_t id)
bool	adaptyst_is_workflow_running (amod_t id)

Macro Definition Documentation

ADAPTYST_ERR_EXCEPTION

#define ADAPTYST_ERR_EXCEPTION   3

Error indicating that a C++ exception occurred on the Adaptyst side. Numerical value: 3

ADAPTYST_ERR_INIT_ONLY

#define ADAPTYST_ERR_INIT_ONLY   6

Error indicating that an API method meant to be called inside adaptyst_module_init() only has been attempted to be called outside of adaptyst_module_init(). Numerical value: 6

ADAPTYST_ERR_LOG_DIR_CREATE

#define ADAPTYST_ERR_LOG_DIR_CREATE   5

Error indicating that Adaptyst couldn't create log directories for the current performance analysis session. Numerical value: 5

ADAPTYST_ERR_MODULE_NOT_FOUND

#define ADAPTYST_ERR_MODULE_NOT_FOUND   1

Error indicating that a module with the specified ID hasn't been found. Numerical value: 1

ADAPTYST_ERR_OUT_OF_MEMORY

#define ADAPTYST_ERR_OUT_OF_MEMORY   2

Error indicating that there is no memory left. Numerical value: 2

ADAPTYST_ERR_TERMINAL_NOT_INITIALISED

#define ADAPTYST_ERR_TERMINAL_NOT_INITIALISED   4

Error indicating that the terimnal-related resources in Adaptyst haven't been initialised yet. Numerical value: 4

ADAPTYST_ERR_TIMEOUT

#define ADAPTYST_ERR_TIMEOUT   7

Error indicating a timeout. Numerical value: 7

ADAPTYST_ERR_TIMESTAMP

#define ADAPTYST_ERR_TIMESTAMP   9

Error indicating that the timestamp couldn't be obtained. Numerical value: 9

ADAPTYST_ERR_WORKFLOW_NOT_STARTED

#define ADAPTYST_ERR_WORKFLOW_NOT_STARTED   8

Error indicating that the workflow hasn't been started. Numerical value: 8

ADAPTYST_ERR_WORKFLOW_RUNNING

#define ADAPTYST_ERR_WORKFLOW_RUNNING   10

Error indicating that the workflow is still running. Numerical value: 10

ADAPTYST_OK

#define ADAPTYST_OK   0

No error has occurred. Numerical value: 0

Enumeration Type Documentation

option_type

enum option_type

Enum describing a value type of a module option.

Enumerator
INT	C: int
STRING	C: const char *
UNSIGNED_INT	C: unsigned int
BOOL	C: bool
NONE	No type.

profile_type

enum profile_type

Enum describing workflow execution types.

Enumerator
LINUX_PROCESS	Workflow is executed as a Linux process.

Function Documentation

adaptyst_get_cpu_mask()

const char * adaptyst_get_cpu_mask

(

amod_t

id

)

Gets the CPU mask, which length is equal to the number of CPU cores and where the i-th char (indexing and core numbering from 1) can be either: 'b': the i-th core is for both workflow execution and performance analysis 'p': the i-th core is for performance analysis only 'c': the i-th core is for workflow execution only ' ': the i-th core is not used

This method can be called inside adaptyst_module_init() ONLY. Otherwise, an error will be thrown.

Parameters

id	The module ID (use module_id).

Returns

The CPU mask or a null pointer if the operation hasn't been successful.

adaptyst_get_internal_error_code()

int adaptyst_get_internal_error_code

(

amod_t

id

)

Gets the error code set by any of the Adaptyst API calls.

Parameters

id	The module ID (use module_id).

Returns

Error code or 0 if no error has occurred. See the ADAPTYST_OK and ADAPTYST_ERR_* definitions for possible error codes.

adaptyst_get_internal_error_msg()

const char * adaptyst_get_internal_error_msg

(

amod_t

id

)

Gets the error message set by any of the Adaptyst API calls.

Parameters

id	The module ID (use module_id).

Returns

Error message or a null pointer if no error has occurred.

adaptyst_get_library_dir()

const char * adaptyst_get_library_dir

(

amod_t

id

)

Gets the path of a loaded module library (e.g. if the library is /A/B/C/libmodule.so, the return value is /A/B/C/libmodule.so).

Parameters

id	The module ID (use module_id).

Returns

The path of a loaded module.

adaptyst_get_local_config_dir()

const char * adaptyst_get_local_config_dir

(

amod_t

id

)

Gets the path to a directory where Adaptyst local configuration files are stored.

Parameters

id	The module ID (use module_id).

Returns

The path to the local config directory or a null pointer if the operation hasn't been successful.

adaptyst_get_log_dir()

const char * adaptyst_get_log_dir

(

amod_t

id

)

Gets the path to a directory where Adaptyst logs are stored.

Parameters

id	The module ID (use module_id).

Returns

The path to the Adaptyst log directory or a null pointer if the operation hasn't been successful.

adaptyst_get_module_dir()

const char * adaptyst_get_module_dir

(

amod_t

id

)

Gets the path to a directory where all module output files should be stored.

Parameters

id	The module ID (use module_id).

Returns

The path to the module output directory or a null pointer if the operation hasn't been successful.

adaptyst_get_node_name()

const char * adaptyst_get_node_name

(

amod_t

id

)

Gets the name of a node a module is attached to.

Parameters

id	The module ID (use module_id).

Returns

The name of the node or a null pointer if the operation hasn't been successful.

adaptyst_get_option()

option * adaptyst_get_option	(	amod_t	id,
		const char *	key
	)

Gets a module option set by a user.

Parameters

id	The module ID (use module_id).
key	The name of an option to obtain.

Returns

Pointer to the option struct corresponding to an option with the given name or a null pointer if the option couldn't be found.

adaptyst_get_profile_info()

profile_info * adaptyst_get_profile_info

(

amod_t

id

)

Gets information necessary for profiling a workflow in form of a profile_info struct.

Parameters

id	The module ID (use module_id).

Returns

Pointer to the profile_info struct with profiling information or a null pointer if the operation hasn't been successful.

adaptyst_get_timestamp()

unsigned long long adaptyst_get_timestamp

(

amod_t

id

)

Gets the current timestamp in nanoseconds in the Unix format.

Parameters

id	The module ID (use module_id).

Returns

Timestamp if no errors have occurred, 0 otherwise with adaptyst_get_internal_error_code() returning ADAPTYST_ERR_TIMESTAMP or ADAPTYST_ERR_MODULE_NOT_FOUND.

adaptyst_get_tmp_dir()

const char * adaptyst_get_tmp_dir

(

amod_t

id

)

Gets the path to a temporary directory.

Parameters

id	The module ID (use module_id).

Returns

The path to a temporary directory or a null pointer if the operation hasn't been successful.

adaptyst_get_workflow_end_time()

unsigned long long adaptyst_get_workflow_end_time

(

amod_t

id

)

Gets the timestamp in nanoseconds in the Unix format of when the workflow has finished executing in an entity where the module is.

Parameters

id	The module ID (use module_id).

Returns

Time of the workflow end in the Unix timestamp format if the operation is successful, 0 otherwise with adaptyst_get_internal_error_code() returning ADAPTYST_ERR_*. If the workflow hasn't been started, the error code is ADAPTYST_ERR_WORKFLOW_NOT_STARTED. If the workflow is still running, the error code is ADAPTYST_ERR_WORKFLOW_RUNNING.

adaptyst_get_workflow_start_time()

unsigned long long adaptyst_get_workflow_start_time

(

amod_t

id

)

Gets the timestamp in nanoseconds in the Unix format of when the workflow has been started in an entity where the module is.

Specifically, the timestamp refers to the moment when the workflow has been started following modules indicating their readiness to run performance analysis.

Parameters

id	The module ID (use module_id).

Returns

Time of the workflow start in the Unix timestamp format if the operation is successful, 0 otherwise with adaptyst_get_internal_error_code() returning ADAPTYST_ERR_*. If the workflow hasn't been started, the error code is ADAPTYST_ERR_WORKFLOW_NOT_STARTED.

adaptyst_has_in_tag()

bool adaptyst_has_in_tag	(	amod_t	id,
		const char *	tag
	)

Checks whether any nodes connected to a node a module is attached to (i.e. any nodes with an edge to the module node) has a specific tag.

Parameters

id	The module ID (use module_id).
tag	Tag to check.

Returns

Whether any nodes connected to the node has the tag. If the operation hasn't been successful, false is returned.

adaptyst_has_out_tag()

bool adaptyst_has_out_tag	(	amod_t	id,
		const char *	tag
	)

Checks whether any nodes a module node is connected to (i.e. any nodes with an edge from the module node) has a specific tag.

Parameters

id	The module ID (use module_id).
tag	Tag to check.

Returns

Whether any nodes the node is connected to has the tag. If the operation hasn't been successful, false is returned.

adaptyst_is_directing_node()

bool adaptyst_is_directing_node

(

amod_t

id

)

Returns whether a node a module is attached to is a directing node.

Returns

Whether the node is a directing node. If the operation hasn't been successful, false is returned.

adaptyst_is_workflow_running()

bool adaptyst_is_workflow_running

(

amod_t

id

)

Gets whether the workflow is currently running in an entity where the module is.

If the workflow is ready to run but modules haven't indicated their readiness to run performance analysis yet, the return value is true.

Parameters

id	The module ID (use module_id).

Returns

Whether the workflow is running. If the return value is false, this means that either the workflow has finished executing or hasn't been run.

WARNING: If the operation hasn't been successful, the return value is also false! However, you can determine that this is the cause of your problem by checking the value of adaptyst_get_internal_error_code().

adaptyst_log()

bool adaptyst_log	(	amod_t	id,
		const char *	msg,
		const char *	type
	)

Prints an unformatted message of a given type to Adaptyst logs.

Parameters

id	The module ID (use module_id).
msg	Message to log.
type	Log type (use one of the types declared in log_types).

Returns

Whether the operation has been successful.

adaptyst_print()

bool adaptyst_print	(	amod_t	id,
		const char *	msg,
		bool	sub,
		bool	error,
		const char *	type
	)

Prints a formatted message of a given type to Adaptyst logs, i.e. with a specific prefix indicating whether a message is a main one or a secondary one and whether a message is an error.

Parameters

id	The module ID (use module_id).
msg	Message to print.
sub	Whether a message is a secondary one (if true, "->" is printed before the message, otherwise "==>" is printed).
error	Whether a message is an error message.
type	Log type (use one of the types declared in log_types).

Returns

Whether the operation has been successful.

adaptyst_process_src_paths()

bool adaptyst_process_src_paths	(	amod_t	id,
		const char **	paths,
		int	n
	)

Sends source code paths to Adaptyst for further processing (source code packing etc. is handled by Adaptyst, not modules).

Parameters

id	The module ID (use module_id).
paths	Array of source code paths.
n	Number of source code paths.

Returns

Whether the operation has been successful.

adaptyst_profile_notify()

bool adaptyst_profile_notify

(

amod_t

id

)

Sends a notification to Adaptyst that a module is ready to profile.

Parameters

id	The module ID (use module_id).

Returns

Whether the operation has been successful.

adaptyst_profile_wait()

int adaptyst_profile_wait

(

amod_t

id

)

Waits for a workflow executed by Adaptyst to finish running.

Parameters

id	The module ID (use module_id).

Returns

Exit code of the workflow or -1 if the operation hasn't been successful.

adaptyst_receive_data()

bool adaptyst_receive_data	(	amod_t	id,
		char *	buf,
		unsigned int	buf_size,
		int *	n
	)

Receives data from the injection part of the module in a workflow, with no timeout.

Parameters

id	The module ID (use module_id).
buf	Buffer where received data should be stored.
buf_size	Size of the buffer in bytes.
n	Pointer to a variable where the number of received bytes should be stored.

Returns

Whether the operation has been successful.

adaptyst_receive_data_timeout()

bool adaptyst_receive_data_timeout	(	amod_t	id,
		char *	buf,
		unsigned int	buf_size,
		int *	n,
		long	timeout_seconds
	)

Receives data from the injection part of the module in a workflow, with a specific timeout.

Parameters

id	The module ID (use module_id).
buf	Buffer where received data should be stored.
buf_size	Size of the buffer in bytes.
n	Pointer to a variable where the number of received bytes should be stored.
timeout_seconds	Timeout in seconds.

Returns

Whether the operation has been successful (it's false with adaptyst_get_internal_error_code() returning ADAPTYST_ERR_TIMEOUT in case of timeout).

adaptyst_receive_string()

bool adaptyst_receive_string	(	amod_t	id,
		const char **	str
	)

Receives a string from the injection part of the module in a workflow, with no timeout.

If the sender has sent n strings using adaptyst_send_string() (where n is a positive integer), adaptyst_receive_string() or its timeout variant must be called n times to receive all of these, in the order they have been sent in.

Parameters

id	The module ID (use module_id).
str	Pointer to a variable where the received string should be stored. If 0 bytes are received, the variable is set to a null pointer.

Returns

Whether the operation has been successful.

adaptyst_receive_string_timeout()

bool adaptyst_receive_string_timeout	(	amod_t	id,
		const char **	str,
		long	timeout_seconds
	)

Receives a string from the injection part of the module in a workflow, with a specific timeout.

If the sender has sent n strings using adaptyst_send_string() (where n is a positive integer), adaptyst_receive_string_timeout() or its non-timeout variant must be called n times to receive all of these, in the order they have been sent in.

Parameters

id	The module ID (use module_id).
str	Pointer to a variable where the received string should be stored. If 0 bytes are received, the variable is set to a null pointer.
timeout_seconds	Timeout in seconds.

Returns

Whether the operation has been successful (it's false with adaptyst_get_internal_error_code() returning ADAPTYST_ERR_TIMEOUT in case of timeout).

adaptyst_send_data()

bool adaptyst_send_data	(	amod_t	id,
		char *	buf,
		unsigned int	n
	)

Sends data to the injection part of the module in a workflow.

Parameters

id	The module ID (use module_id).
buf	Data to send.
n	Number of bytes to send.

Returns

Whether the operation has been successful.

adaptyst_send_string()

bool adaptyst_send_string	(	amod_t	id,
		const char *	str
	)

Sends a string to the injection part of the module in a workflow.

The recipient receives strings in the same order they are sent in as long as the sender uses adaptyst_send_string() and the receiver uses adaptyst_receive_string() or its timeout variant.

Parameters

id	The module ID (use module_id).
str	String to send.

Returns

Whether the operation has been successful.

adaptyst_set_error()

bool adaptyst_set_error	(	amod_t	id,
		const char *	msg
	)

Indicates to Adaptyst that a module error has occurred.

Parameters

id	The module ID (use module_id).
msg	Error message.

Returns

Whether the operation has been successful.

adaptyst_set_profile_info()

bool adaptyst_set_profile_info	(	amod_t	id,
		profile_info *	info
	)

Sets information necessary for profiling a workflow in form of a profile_info struct. This function propagates information to all modules within an entity and is useful in case a module is in a directing node.

This method can be called inside adaptyst_module_init() ONLY. Otherwise, an error will be thrown.

Parameters

id	The module ID (use module_id).
info	Pointer to a profile_info struct with profiling information to be set.

Returns

Whether the operation has been successful.

adaptyst_set_will_profile()

bool adaptyst_set_will_profile	(	amod_t	id,
		bool	will_profile
	)

Indicates to Adaptyst whether a module will profile a workflow. By default, Adaptyst assumes that modules do not profile.

This method can be called inside adaptyst_module_init() ONLY. Otherwise, an error will be thrown.

Parameters

id	The module ID (use module_id).
will_profile	Whether a module will profile a workflow.

Returns

Whether the operation has been successful.