Writing interface for OTF2 archives. More...

#include <stdint.h>
#include <otf2/OTF2_ErrorCodes.h>
#include <otf2/OTF2_Callbacks.h>
#include <otf2/OTF2_DefWriter.h>
#include <otf2/OTF2_DefReader.h>
#include <otf2/OTF2_EvtWriter.h>
#include <otf2/OTF2_EvtReader.h>
#include <otf2/OTF2_SnapWriter.h>
#include <otf2/OTF2_SnapReader.h>
#include <otf2/OTF2_GlobalDefWriter.h>
#include <otf2/OTF2_GlobalDefReader.h>
#include <otf2/OTF2_GlobalEvtReader.h>
#include <otf2/OTF2_GlobalSnapReader.h>
#include <otf2/OTF2_Thumbnail.h>
#include <otf2/OTF2_MarkerWriter.h>
#include <otf2/OTF2_MarkerReader.h>

Defines
#define	OTF2_CHUNK_SIZE_DEFINITIONS_DEFAULT ( 4 * 1024 * 1024 )
	Default size for OTF2's internal event chunk memory handling.
#define	OTF2_CHUNK_SIZE_EVENTS_DEFAULT ( 1024 * 1024 )
	Default size for OTF2's internal event chunk memory handling.
Typedefs
typedef struct OTF2_Archive_struct	OTF2_Archive
	Keeps all meta-data for an OTF2 archive.
Functions
OTF2_ErrorCode	OTF2_Archive_Close (OTF2_Archive *archive)
	Close an opened archive.
OTF2_ErrorCode	OTF2_Archive_CloseDefFiles (OTF2_Archive *archive)
	Closes the local definitions file container.
OTF2_ErrorCode	OTF2_Archive_CloseDefReader (OTF2_Archive archive, OTF2_DefReader reader)
	Close an opened local definition reader.
OTF2_ErrorCode	OTF2_Archive_CloseDefWriter (OTF2_Archive archive, OTF2_DefWriter writer)
	Close an opened local definition writer.
OTF2_ErrorCode	OTF2_Archive_CloseEvtFiles (OTF2_Archive *archive)
	Closes the events file container.
OTF2_ErrorCode	OTF2_Archive_CloseEvtReader (OTF2_Archive archive, OTF2_EvtReader reader)
	Close an opened local event reader.
OTF2_ErrorCode	OTF2_Archive_CloseEvtWriter (OTF2_Archive archive, OTF2_EvtWriter writer)
	Close an opened local event writer.
OTF2_ErrorCode	OTF2_Archive_CloseGlobalDefReader (OTF2_Archive archive, OTF2_GlobalDefReader globalDefReader)
	Closes the global definition reader.
OTF2_ErrorCode	OTF2_Archive_CloseGlobalDefWriter (OTF2_Archive archive, OTF2_GlobalDefWriter writer)
	Close an opened global definition writer.
OTF2_ErrorCode	OTF2_Archive_CloseGlobalEvtReader (OTF2_Archive archive, OTF2_GlobalEvtReader globalEvtReader)
	Closes the global event reader.
OTF2_ErrorCode	OTF2_Archive_CloseGlobalSnapReader (OTF2_Archive archive, OTF2_GlobalSnapReader globalSnapReader)
	Close the opened global snapshot reader.
OTF2_ErrorCode	OTF2_Archive_CloseMarkerReader (OTF2_Archive archive, OTF2_MarkerReader markerReader)
	Closes the marker reader.
OTF2_ErrorCode	OTF2_Archive_CloseMarkerWriter (OTF2_Archive archive, OTF2_MarkerWriter writer)
	Close an opened marker writer.
OTF2_ErrorCode	OTF2_Archive_CloseSnapFiles (OTF2_Archive *archive)
	Closes the snapshots file container.
OTF2_ErrorCode	OTF2_Archive_CloseSnapReader (OTF2_Archive archive, OTF2_SnapReader reader)
	Close an opened local snap reader.
OTF2_ErrorCode	OTF2_Archive_CloseSnapWriter (OTF2_Archive archive, OTF2_SnapWriter writer)
	Close an opened local snap writer.
OTF2_ErrorCode	OTF2_Archive_CloseThumbReader (OTF2_Archive archive, OTF2_ThumbReader reader)
	Close an opened thumbnail reader.
OTF2_ErrorCode	OTF2_Archive_GetChunkSize (OTF2_Archive archive, uint64_t chunkSizeEvents, uint64_t *chunkSizeDefs)
	Get the chunksize.
OTF2_ErrorCode	OTF2_Archive_GetCompression (OTF2_Archive archive, OTF2_Compression compression)
	Get compression mode (none or zlib)
OTF2_ErrorCode	OTF2_Archive_GetCreator (OTF2_Archive archive, char *creator)
	Get creator information.
OTF2_DefReader *	OTF2_Archive_GetDefReader (OTF2_Archive *archive, OTF2_LocationRef location)
	Get a local definition reader.
OTF2_DefWriter *	OTF2_Archive_GetDefWriter (OTF2_Archive *archive, OTF2_LocationRef location)
	Get a local definition writer.
OTF2_ErrorCode	OTF2_Archive_GetDescription (OTF2_Archive archive, char *description)
	Get description.
OTF2_EvtReader *	OTF2_Archive_GetEvtReader (OTF2_Archive *archive, OTF2_LocationRef location)
	Get a local event reader.
OTF2_EvtWriter *	OTF2_Archive_GetEvtWriter (OTF2_Archive *archive, OTF2_LocationRef location)
	Get a local event writer.
OTF2_ErrorCode	OTF2_Archive_GetFileSubstrate (OTF2_Archive archive, OTF2_FileSubstrate substrate)
	Get the file substrate (posix, sion, none)
OTF2_GlobalDefReader *	OTF2_Archive_GetGlobalDefReader (OTF2_Archive *archive)
	Get a global definition reader.
OTF2_GlobalDefWriter *	OTF2_Archive_GetGlobalDefWriter (OTF2_Archive *archive)
	Get a global definition writer.
OTF2_GlobalEvtReader *	OTF2_Archive_GetGlobalEvtReader (OTF2_Archive *archive)
	Get a global event reader.
OTF2_GlobalSnapReader *	OTF2_Archive_GetGlobalSnapReader (OTF2_Archive *archive)
	Get a global snap reader.
OTF2_ErrorCode	OTF2_Archive_GetMachineName (OTF2_Archive archive, char *machineName)
	Get machine name.
OTF2_MarkerReader *	OTF2_Archive_GetMarkerReader (OTF2_Archive *archive)
	Get a marker reader.
OTF2_MarkerWriter *	OTF2_Archive_GetMarkerWriter (OTF2_Archive *archive)
	Get a marker writer.
OTF2_ErrorCode	OTF2_Archive_GetNumberOfGlobalDefinitions (OTF2_Archive archive, uint64_t numberOfDefinitions)
	Get the number of global definitions.
OTF2_ErrorCode	OTF2_Archive_GetNumberOfLocations (OTF2_Archive archive, uint64_t numberOfLocations)
	Get the number of locations.
OTF2_ErrorCode	OTF2_Archive_GetNumberOfSnapshots (OTF2_Archive archive, uint32_t number)
	Get the number of snapshots.
OTF2_ErrorCode	OTF2_Archive_GetNumberOfThumbnails (OTF2_Archive archive, uint32_t number)
	Get the number of thumbnails.
OTF2_ErrorCode	OTF2_Archive_GetProperty (OTF2_Archive archive, const char name, char **value)
	Get the value of the named trace file property.
OTF2_ErrorCode	OTF2_Archive_GetPropertyNames (OTF2_Archive archive, uint32_t numberOfProperties, char ***names)
	Get the names of all trace file properties.
OTF2_SnapReader *	OTF2_Archive_GetSnapReader (OTF2_Archive *archive, OTF2_LocationRef location)
	Get a local snap reader.
OTF2_SnapWriter *	OTF2_Archive_GetSnapWriter (OTF2_Archive *archive, OTF2_LocationRef location)
	Get a local snap writer.
OTF2_ThumbReader *	OTF2_Archive_GetThumbReader (OTF2_Archive *archive, uint32_t number)
	Get a thumb reader.
OTF2_ThumbWriter *	OTF2_Archive_GetThumbWriter (OTF2_Archive archive, const char name, const char description, OTF2_ThumbnailType type, uint32_t numberOfSamples, uint32_t numberOfMetrics, const uint64_t refsToDefs)
	Get a thumb writer.
OTF2_ErrorCode	OTF2_Archive_GetTraceId (OTF2_Archive archive, uint64_t id)
	Get the identifier of the trace file.
OTF2_ErrorCode	OTF2_Archive_GetVersion (OTF2_Archive archive, uint8_t major, uint8_t minor, uint8_t bugfix)
	Get format version.
OTF2_Archive *	OTF2_Archive_Open (const char archivePath, const char archiveName, const OTF2_FileMode fileMode, const uint64_t chunkSizeEvents, const uint64_t chunkSizeDefs, const OTF2_FileSubstrate fileSubstrate, const OTF2_Compression compression)
	Create a new archive.
OTF2_ErrorCode	OTF2_Archive_OpenDefFiles (OTF2_Archive *archive)
	Open the local definitions file container.
OTF2_ErrorCode	OTF2_Archive_OpenEvtFiles (OTF2_Archive *archive)
	Open the events file container.
OTF2_ErrorCode	OTF2_Archive_OpenSnapFiles (OTF2_Archive *archive)
	Open the snapshots file container.
OTF2_ErrorCode	OTF2_Archive_SelectLocation (OTF2_Archive *archive, OTF2_LocationRef location)
	Select a location to be read.
OTF2_ErrorCode	OTF2_Archive_SetBoolProperty (OTF2_Archive archive, const char name, bool value, bool overwrite)
	Add or remove a boolean trace file property to this archive.
OTF2_ErrorCode	OTF2_Archive_SetCollectiveCallbacks (OTF2_Archive archive, const OTF2_CollectiveCallbacks collectiveCallbacks, void collectiveData, OTF2_CollectiveContext globalCommContext, OTF2_CollectiveContext *localCommContext)
	Set the collective callbacks for the archive.
OTF2_ErrorCode	OTF2_Archive_SetCreator (OTF2_Archive archive, const char creator)
	Set creator.
OTF2_ErrorCode	OTF2_Archive_SetDescription (OTF2_Archive archive, const char description)
	Set a description.
OTF2_ErrorCode	OTF2_Archive_SetFlushCallbacks (OTF2_Archive archive, const OTF2_FlushCallbacks flushCallbacks, void *flushData)
	Set the flush callbacks for the archive.
OTF2_ErrorCode	OTF2_Archive_SetHint (OTF2_Archive archive, OTF2_Hint hint, void value)
	Set the hint in the archive to the given value.
OTF2_ErrorCode	OTF2_Archive_SetLockingCallbacks (OTF2_Archive archive, const OTF2_LockingCallbacks lockingCallbacks, void *lockingData)
	Set the locking callbacks for the archive.
OTF2_ErrorCode	OTF2_Archive_SetMachineName (OTF2_Archive archive, const char machineName)
	Set machine name.
OTF2_ErrorCode	OTF2_Archive_SetMemoryCallbacks (OTF2_Archive archive, const OTF2_MemoryCallbacks memoryCallbacks, void *memoryData)
	Set the memory callbacks for the archive.
OTF2_ErrorCode	OTF2_Archive_SetNumberOfSnapshots (OTF2_Archive *archive, uint32_t number)
	Set the number of snapshots.
OTF2_ErrorCode	OTF2_Archive_SetProperty (OTF2_Archive archive, const char name, const char *value, bool overwrite)
	Add or remove a trace file property to this archive.
OTF2_ErrorCode	OTF2_Archive_SetSerialCollectiveCallbacks (OTF2_Archive *archive)
	Convenient function to set the collective callbacks to an serial implementation.
OTF2_ErrorCode	OTF2_Archive_SwitchFileMode (OTF2_Archive *archive, OTF2_FileMode newFileMode)
	Switch file mode of the archive.

Detailed Description

Writing interface for OTF2 archives.

Define Documentation

#define OTF2_CHUNK_SIZE_DEFINITIONS_DEFAULT ( 4 * 1024 * 1024 )

Default size for OTF2's internal event chunk memory handling.

If you are not sure which chunk size is the best to use, use this default value.

#define OTF2_CHUNK_SIZE_EVENTS_DEFAULT ( 1024 * 1024 )

Default size for OTF2's internal event chunk memory handling.

If you are not sure which chunk size is the best to use, use this default value.

Typedef Documentation

typedef struct OTF2_Archive_struct OTF2_Archive

Keeps all meta-data for an OTF2 archive.

An OTF2 archive handle keeps all runtime information about an OTF2 archive. It is the central handle to get and set information about the archive and to request event and definition writer handles.

Function Documentation

OTF2_ErrorCode OTF2_Archive_Close ( OTF2_Archive * archive )

Close an opened archive.

Closes an opened archive and releases the associated resources. Closes also all opened writer and reader handles. Does nothing if NULL is passed.

Parameters:

archive Archive handle.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.

OTF2_ErrorCode OTF2_Archive_CloseDefFiles ( OTF2_Archive * archive )

Closes the local definitions file container.

This function is an collective operation.

Parameters:

archive Archive handle.

Since:: Version 1.3

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_CloseDefReader	(	OTF2_Archive *	archive,
		OTF2_DefReader *	reader
	)

Close an opened local definition reader.

Parameters:

archive	Archive handle.
reader	Reader handle to be closed.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_CloseDefWriter	(	OTF2_Archive *	archive,
		OTF2_DefWriter *	writer
	)

Close an opened local definition writer.

Parameters:

archive	Archive handle.
writer	Writer handle to be closed.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_CloseEvtFiles ( OTF2_Archive * archive )

Closes the events file container.

This function is an collective operation.

Parameters:

archive Archive handle.

Since:: Version 1.3

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.

OTF2_ErrorCode OTF2_Archive_CloseEvtReader	(	OTF2_Archive *	archive,
		OTF2_EvtReader *	reader
	)

Close an opened local event reader.

Parameters:

archive	Archive handle.
reader	Reader handle to be closed.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_CloseEvtWriter	(	OTF2_Archive *	archive,
		OTF2_EvtWriter *	writer
	)

Close an opened local event writer.

Parameters:

archive	Archive handle.
writer	Writer handle to be closed.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.

OTF2_ErrorCode OTF2_Archive_CloseGlobalDefReader	(	OTF2_Archive *	archive,
		OTF2_GlobalDefReader *	globalDefReader
	)

Closes the global definition reader.

Parameters:

archive	Archive handle.
globalDefReader	The global definition reader.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_CloseGlobalDefWriter	(	OTF2_Archive *	archive,
		OTF2_GlobalDefWriter *	writer
	)

Close an opened global definition writer.

Only the master archive can call this function.

Parameters:

archive	Archive handle.
writer	Writer handle to be closed.

Returns:

OTF2_SUCCESS

if successful

OTF2_ERROR_INVALID_ARGUMENT

if the archive or writer argument is invalid

OTF2_ERROR_INVALID_CALL

if the archive is not in master mode

Examples:: otf2_mpi_writer_example.c.

OTF2_ErrorCode OTF2_Archive_CloseGlobalEvtReader	(	OTF2_Archive *	archive,
		OTF2_GlobalEvtReader *	globalEvtReader
	)

Closes the global event reader.

This closes also all local event readers.

Parameters:

archive	Archive handle.
globalEvtReader	The global event reader.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_CloseGlobalSnapReader	(	OTF2_Archive *	archive,
		OTF2_GlobalSnapReader *	globalSnapReader
	)

Close the opened global snapshot reader.

Parameters:

archive	Archive handle.
globalSnapReader	Reader handle to be closed.

Since:: Version 1.2

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_CloseMarkerReader	(	OTF2_Archive *	archive,
		OTF2_MarkerReader *	markerReader
	)

Closes the marker reader.

Parameters:

archive	Archive handle.
markerReader	The marker reader.

Since:: Version 1.2

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_CloseMarkerWriter	(	OTF2_Archive *	archive,
		OTF2_MarkerWriter *	writer
	)

Close an opened marker writer.

Parameters:

archive	Archive handle.
writer	Writer handle to be closed.

Since:: Version 1.2

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_CloseSnapFiles ( OTF2_Archive * archive )

Closes the snapshots file container.

This function is an collective operation.

Parameters:

archive Archive handle.

Since:: Version 1.3

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_CloseSnapReader	(	OTF2_Archive *	archive,
		OTF2_SnapReader *	reader
	)

Close an opened local snap reader.

Parameters:

archive	Archive handle.
reader	Reader handle to be closed.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

Since:: Version 1.2

OTF2_ErrorCode OTF2_Archive_CloseSnapWriter	(	OTF2_Archive *	archive,
		OTF2_SnapWriter *	writer
	)

Close an opened local snap writer.

Parameters:

archive	Archive handle.
writer	Writer handle to be closed.

Since:: Version 1.2

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_CloseThumbReader	(	OTF2_Archive *	archive,
		OTF2_ThumbReader *	reader
	)

Close an opened thumbnail reader.

Parameters:

archive	Archive handle.
reader	Reader handle to be closed.

Since:: Version 1.2

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_GetChunkSize	(	OTF2_Archive *	archive,
		uint64_t *	chunkSizeEvents,
		uint64_t *	chunkSizeDefs
	)

Get the chunksize.

Parameters:

	archive	Archive handle.
[out]	chunkSizeEvents	Chunk size for event files.
[out]	chunkSizeDefs	Chunk size for definition files.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_GetCompression	(	OTF2_Archive *	archive,
		OTF2_Compression *	compression
	)

Get compression mode (none or zlib)

Parameters:

	archive	Archive handle.
[out]	compression	Returned compression mode.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_GetCreator	(	OTF2_Archive *	archive,
		char **	creator
	)

Get creator information.

Parameters:

	archive	Archive handle.
[out]	creator	Returned creator. Allocated with malloc.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_DefReader* OTF2_Archive_GetDefReader	(	OTF2_Archive *	archive,
		OTF2_LocationRef	location
	)

Get a local definition reader.

Parameters:

archive	Archive handle.
location	Location ID of the requested reader handle.

Returns:: Returns a local definition reader handle if successful, NULL if an error occurs.

OTF2_DefWriter* OTF2_Archive_GetDefWriter	(	OTF2_Archive *	archive,
		OTF2_LocationRef	location
	)

Get a local definition writer.

Parameters:

archive	Archive handle.
location	Location ID of the requested writer handle.

Returns:: Returns a local definition writer handle if successful, NULL if an error occurs.

OTF2_ErrorCode OTF2_Archive_GetDescription	(	OTF2_Archive *	archive,
		char **	description
	)

Get description.

Parameters:

	archive	Archive handle.
[out]	description	Returned description. Allocated with malloc.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_EvtReader* OTF2_Archive_GetEvtReader	(	OTF2_Archive *	archive,
		OTF2_LocationRef	location
	)

Get a local event reader.

Parameters:

archive	Archive handle.
location	Location ID of the requested reader handle.

Returns:: Returns a local event reader handle if successful, NULL if an error occurs.

OTF2_EvtWriter* OTF2_Archive_GetEvtWriter	(	OTF2_Archive *	archive,
		OTF2_LocationRef	location
	)

Get a local event writer.

Parameters:

archive	Archive handle.
location	Location ID of the requested writer handle.

Returns:: Returns a local event writer handle if successful, NULL if an error occurs.

Examples:: otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.

OTF2_ErrorCode OTF2_Archive_GetFileSubstrate	(	OTF2_Archive *	archive,
		OTF2_FileSubstrate *	substrate
	)

Get the file substrate (posix, sion, none)

Parameters:

	archive	Archive handle.
[out]	substrate	Returned file substrate.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_GlobalDefReader* OTF2_Archive_GetGlobalDefReader ( OTF2_Archive * archive )

Get a global definition reader.

Only the master archive can call this function.

Parameters:

archive Archive handle.

Returns:: Returns a global definition reader handle if successful, NULL if an error occurs.

OTF2_GlobalDefWriter* OTF2_Archive_GetGlobalDefWriter ( OTF2_Archive * archive )

Get a global definition writer.

Parameters:

archive Archive handle.

Returns:: Returns a global definition writer handle if successful, NULL if an error occurs.

Examples:: otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.

OTF2_GlobalEvtReader* OTF2_Archive_GetGlobalEvtReader ( OTF2_Archive * archive )

Get a global event reader.

Parameters:

archive Archive handle.

Returns:: Returns a global event reader handle if successful, NULL if an error occurs.

OTF2_GlobalSnapReader* OTF2_Archive_GetGlobalSnapReader ( OTF2_Archive * archive )

Get a global snap reader.

Parameters:

archive Archive handle.

Since:: Version 1.2

Returns:: Returns a global snap reader handle if successful, NULL if an error occurs.

OTF2_ErrorCode OTF2_Archive_GetMachineName	(	OTF2_Archive *	archive,
		char **	machineName
	)

Get machine name.

Parameters:

	archive	Archive handle.
[out]	machineName	Returned machine name. Allocated with malloc.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_MarkerReader* OTF2_Archive_GetMarkerReader ( OTF2_Archive * archive )

Get a marker reader.

Parameters:

archive Archive handle.

Since:: Version 1.2

Returns:: Returns a marker reader handle if successful, NULL if an error occurs.

OTF2_MarkerWriter* OTF2_Archive_GetMarkerWriter ( OTF2_Archive * archive )

Get a marker writer.

Parameters:

archive Archive handle.

Since:: Version 1.2

Returns:: Returns a marker writer handle if successful, NULL if an error occurs.

OTF2_ErrorCode OTF2_Archive_GetNumberOfGlobalDefinitions	(	OTF2_Archive *	archive,
		uint64_t *	numberOfDefinitions
	)

Get the number of global definitions.

Parameters:

	archive	Archive handle.
[out]	numberOfDefinitions	Return pointer to the number of global definitions.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_GetNumberOfLocations	(	OTF2_Archive *	archive,
		uint64_t *	numberOfLocations
	)

Get the number of locations.

Parameters:

	archive	Archive handle.
[out]	numberOfLocations	Return pointer to the number of locations.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_GetNumberOfSnapshots	(	OTF2_Archive *	archive,
		uint32_t *	number
	)

Get the number of snapshots.

Parameters:

archive	Archive handle.
number	Snapshot number.

Since:: Version 1.2

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_GetNumberOfThumbnails	(	OTF2_Archive *	archive,
		uint32_t *	number
	)

Get the number of thumbnails.

Parameters:

archive	Archive handle.
number	Thumb number.

Since:: Version 1.2

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_GetProperty	(	OTF2_Archive *	archive,
		const char *	name,
		char **	value
	)

Get the value of the named trace file property.

Parameters:

	archive	Archive handle.
	name	Name of the property.
[out]	value	Returned value of the property. Allocated with malloc.

Returns:

OTF2_SUCCESS

if successful

OTF2_ERROR_PROPERTY_NOT_FOUND

if the named property was not found

OTF2_ErrorCode OTF2_Archive_GetPropertyNames	(	OTF2_Archive *	archive,
		uint32_t *	numberOfProperties,
		char ***	names
	)

Get the names of all trace file properties.

Parameters:

	archive	Archive handle.
[out]	numberOfProperties	Returned number of trace file properties.
[out]	names	Returned list of property names. Allocated with malloc. To release memory, just pass `names` to free*.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_SnapReader* OTF2_Archive_GetSnapReader	(	OTF2_Archive *	archive,
		OTF2_LocationRef	location
	)

Get a local snap reader.

Parameters:

archive	Archive handle.
location	Location ID of the requested snap handle.

Since:: Version 1.2

Returns:: Returns a local snap handle if successful, NULL if an error occurs.

OTF2_SnapWriter* OTF2_Archive_GetSnapWriter	(	OTF2_Archive *	archive,
		OTF2_LocationRef	location
	)

Get a local snap writer.

Parameters:

archive	Archive handle.
location	Location ID of the requested writer handle.

Since:: Version 1.2

Returns:: Returns a local event writer handle if successful, NULL if an error occurs.

OTF2_ThumbReader* OTF2_Archive_GetThumbReader	(	OTF2_Archive *	archive,
		uint32_t	number
	)

Get a thumb reader.

Parameters:

archive	Archive handle.
number	Thumbnail number.

Since:: Version 1.2

Returns:: Returns a global definition writer handle if successful, NULL if an error occurs.

OTF2_ThumbWriter* OTF2_Archive_GetThumbWriter	(	OTF2_Archive *	archive,
		const char *	name,
		const char *	description,
		OTF2_ThumbnailType	type,
		uint32_t	numberOfSamples,
		uint32_t	numberOfMetrics,
		const uint64_t *	refsToDefs
	)

Get a thumb writer.

Parameters:

archive	Archive handle.
name	Name of thumb.
description	Description of thumb.
type	Type of thumb.
numberOfSamples	Number of samples.
numberOfMetrics	Number of metrics.
refsToDefs	numberOfMetrics references to defintion matching the thumbnail type.

Since:: Version 1.2

Returns:: Returns a thumb writer handle if successful, NULL if an error occurs.

OTF2_ErrorCode OTF2_Archive_GetTraceId	(	OTF2_Archive *	archive,
		uint64_t *	id
	)

Get the identifier of the trace file.

Note:: This call is only allowed when the archive was opened with mode OTF2_FILEMODE_READ.

Parameters:

	archive	Archive handle.
[out]	id	Trace identifier.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_GetVersion	(	OTF2_Archive *	archive,
		uint8_t *	major,
		uint8_t *	minor,
		uint8_t *	bugfix
	)

Get format version.

Parameters:

	archive	Archive handle
[out]	major	Major version number
[out]	minor	Minor version number
[out]	bugfix	Bugfix revision

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_Archive* OTF2_Archive_Open	(	const char *	archivePath,
		const char *	archiveName,
		const OTF2_FileMode	fileMode,
		const uint64_t	chunkSizeEvents,
		const uint64_t	chunkSizeDefs,
		const OTF2_FileSubstrate	fileSubstrate,
		const OTF2_Compression	compression
	)

Create a new archive.

Creates a new archive handle that keeps all meta data about the archive on runtime.

Parameters:

archivePath	Path to the archive i.e. the directory where the anchor file is located.
archiveName	Name of the archive. It is used to generate sub pathes e.g. 'archiveName.otf2'.
fileMode	Determines if in reading or writing mode. Available values are OTF2_FILEMODE_WRITE or OTF2_FILEMODE_READ.
chunkSizeEvents	Requested size of OTF2's internal event chunks in writing mode. Available values are from 256kB to 16MB. The event chunk size affects performance as well as total memory usage. A value satisfying both is about 1MB. If you are not sure which chunk size is the best to use, use OTF2_CHUNK_SIZE_EVENTS_DEFAULT. In reading mode this value is ignored because the correct chunk size is extracted from the anchor file.
chunkSizeDefs	Requested size of OTF2's internal definition chunks in writing mode. Available values are from 256kB to 16MB. The definition chunk size affects performance as well as total memory usage. In addition, the definition chunk size must be big enough to carry the largest possible definition record. Therefore, the definition chunk size must be at least 10 times the number of locations. A value satisfying these requirements is about 4MB. If you are not sure which chunk size is the best to use, use OTF2_CHUNK_SIZE_DEFINITIONS_DEFAULT. In reading mode this value is ignored because the correct chunk size is extracted from the anchor file.
fileSubstrate	Determines which file substrate should be used in writing mode. Available values are OTF2_SUBSTRATE_POSIX to use the standard Posix interface, OTF2_SUBSTRATE_SION to use an installed SION library to store multiple logical files into fewer or one physical file, and OTF2_SUBSTRATE_NONE to supress file writing at all. In reading mode this value is ignored because the correct file substrated is extracted from the anchor file.
compression	Determines if compression is used to reduce the size of data in files. Available values are OTF2_COMPRESSION_ZLIB to use an installed zlib and OTF2_COMPRESSION_NONE to disable compression. In reading mode this value is ignored because the correct file compression is extracted from the anchor file.

Returns:: Returns an archive handle if successful, NULL otherwise.

Examples:: otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.

OTF2_ErrorCode OTF2_Archive_OpenDefFiles ( OTF2_Archive * archive )

Open the local definitions file container.

This function is an collective operation.

Parameters:

archive Archive handle.

Since:: Version 1.3

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_OpenEvtFiles ( OTF2_Archive * archive )

Open the events file container.

This function is an collective operation.

Parameters:

archive Archive handle.

Since:: Version 1.3

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.

OTF2_ErrorCode OTF2_Archive_OpenSnapFiles ( OTF2_Archive * archive )

Open the snapshots file container.

This function is an collective operation.

Parameters:

archive Archive handle.

Since:: Version 1.3

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_SelectLocation	(	OTF2_Archive *	archive,
		OTF2_LocationRef	location
	)

Select a location to be read.

Parameters:

archive	Archive handle.
location	Location ID.

Since:: Version 1.3

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_SetBoolProperty	(	OTF2_Archive *	archive,
		const char *	name,
		bool	value,
		bool	overwrite
	)

Add or remove a boolean trace file property to this archive.

Note:: This call is only allowed when the archive was opened with mode OTF2_FILEMODE_WRITE.

Parameters:

archive	Archive handle.
name	Name of the trace file property (case insensitive, [A-Z0-9_]).
value	Boolean value of property (e.g. true or false).
overwrite	If true a previous trace file property with the same name `name` will be overwritten.

Returns:

OTF2_SUCCESS

if successful

OTF2_ERROR_PROPERTY_NAME_INVALID

if property name does not conform to the naming scheme

OTF2_ERROR_PROPERTY_NOT_FOUND

if property was not found, but requested to remove

OTF2_ERROR_PROPERTY_EXISTS

if property exists but overwrite was not set

OTF2_ErrorCode OTF2_Archive_SetCollectiveCallbacks	(	OTF2_Archive *	archive,
		const OTF2_CollectiveCallbacks *	collectiveCallbacks,
		void *	collectiveData,
		OTF2_CollectiveContext *	globalCommContext,
		OTF2_CollectiveContext *	localCommContext
	)

Set the collective callbacks for the archive.

This function is an collective operation.

Parameters:

archive	Archive handle.
collectiveCallbacks	Struct holding the collective callback functions.
collectiveData	Data passed to the collective callbacks in the `userData` argument.
globalCommContext	Global communication context.
localCommContext	Local communication context.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_SetCreator	(	OTF2_Archive *	archive,
		const char *	creator
	)

Set creator.

Sets information about the creator of the trace archive. This value is optional. It only needs to be set for an archive handle marked as 'master' or does not need to be set at all.

Parameters:

archive	Archive handle.
creator	Creator information.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_SetDescription	(	OTF2_Archive *	archive,
		const char *	description
	)

Set a description.

Sets a description for a trace archive. This value is optional. It only needs to be set for an archive handle marked as 'master' or does not need to be set at all.

Parameters:

archive	Archive handle.
description	Description.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_SetFlushCallbacks	(	OTF2_Archive *	archive,
		const OTF2_FlushCallbacks *	flushCallbacks,
		void *	flushData
	)

Set the flush callbacks for the archive.

Parameters:

archive	Archive handle.
flushCallbacks	Struct holding the flush callback functions.
flushData	Data passed to the flush callbacks in the `userData` argument.

Returns:: OTF2_ErrorCode, or error code.

Examples:: otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.

OTF2_ErrorCode OTF2_Archive_SetHint	(	OTF2_Archive *	archive,
		OTF2_Hint	hint,
		void *	value
	)

Set the hint in the archive to the given value.

Hints can only be set once and only before OTF2 itself uses the hint the first time.

Parameters:

archive	Archive handle.
hint	Name of the hint.
value	Reference to the hint value.

Since:: Version 1.5

Returns:

OTF2_SUCCESS

if successful

OTF2_ERROR_INVALID_ARGUMENT

in case of NULL pointers for archive or value, or an unknown hint value

OTF2_ERROR_HINT_INVALID

in case the hint is not valid for this handle

OTF2_ERROR_HINT_LOCKED

in case the hint was already set or was queried at least once by the handle

OTF2_ERROR_HINT_INVALID_VALUE

in case the provided value is invalid for this hint

OTF2_ErrorCode OTF2_Archive_SetLockingCallbacks	(	OTF2_Archive *	archive,
		const OTF2_LockingCallbacks *	lockingCallbacks,
		void *	lockingData
	)

Set the locking callbacks for the archive.

Can be called any time, but only once. Before this call no thread-safety is guaranteed.

Parameters:

archive	Archive handle.
lockingCallbacks	Struct holding the locking callback functions.
lockingData	Data passed to the locking callbacks in the `userData` argument.

Returns:

OTF2_SUCCESS

if successful

OTF2_ERROR_INVALID_ARGUMENT

in case of NULL pointers for archive or lockingCallbacks, or mandatory callbacks in lockingCallbacks are missing

OTF2_ERROR_INVALID_CALL

in case there were locking callbacks already set

OTF2_ErrorCode OTF2_Archive_SetMachineName	(	OTF2_Archive *	archive,
		const char *	machineName
	)

Set machine name.

Sets the name for the machine the trace was recorded. This value is optional. It only needs to be set for an archive handle marked as 'master' or does not need to be set at all.

Parameters:

archive	Archive handle.
machineName	Machine name.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_SetMemoryCallbacks	(	OTF2_Archive *	archive,
		const OTF2_MemoryCallbacks *	memoryCallbacks,
		void *	memoryData
	)

Set the memory callbacks for the archive.

Parameters:

archive	Archive handle.
memoryCallbacks	Struct holding the memory callback functions.
memoryData	Data passed to the memory callbacks in the `userData` argument.

Returns:: OTF2_ErrorCode, or error code.

OTF2_ErrorCode OTF2_Archive_SetNumberOfSnapshots	(	OTF2_Archive *	archive,
		uint32_t	number
	)

Set the number of snapshots.

Parameters:

archive	Archive handle.
number	Snapshot number.

Since:: Version 1.2

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Archive_SetProperty	(	OTF2_Archive *	archive,
		const char *	name,
		const char *	value,
		bool	overwrite
	)

Add or remove a trace file property to this archive.

Removing a trace file property is done by passing "" in the value parameter. The overwrite parameter is ignored than.

Note:: This call is only allowed when the archive was opened with mode OTF2_FILEMODE_WRITE.

Parameters:

archive	Archive handle.
name	Name of the trace file property (case insensitive, [A-Z0-9_]).
value	Value of property.
overwrite	If true a previous trace file property with the same name `name` will be overwritten.

Returns:

OTF2_SUCCESS

if successful

OTF2_ERROR_PROPERTY_NAME_INVALID

if property name does not conform to the naming scheme

OTF2_ERROR_PROPERTY_NOT_FOUND

if property was not found, but requested to remove

OTF2_ERROR_PROPERTY_EXISTS

if property exists but overwrite was not set

OTF2_ErrorCode OTF2_Archive_SetSerialCollectiveCallbacks ( OTF2_Archive * archive )

Convenient function to set the collective callbacks to an serial implementation.

Parameters:

archive Archive handle.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.

OTF2_ErrorCode OTF2_Archive_SwitchFileMode	(	OTF2_Archive *	archive,
		OTF2_FileMode	newFileMode
	)

Switch file mode of the archive.

Currently only a switch from OTF2_FILEMODE_READ to OTF2_FILEMODE_WRITE is permitted. Currrently it is also only permitted when operating on an OTF2 archive with the OTF2_SUBSTRATE_POSIX file substrate.

Parameters:

archive	Archive handle.
newFileMode	New OTF2_FileMode to switch to.

Returns:: OTF2_SUCCESS if successful, an error code if an error occurs.

Since:: Version 1.2

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation