OTF2_EvtReader.h File Reference

This is the local event reader, which reads events from one location. More...

#include <stdint.h>
#include <otf2/OTF2_ErrorCodes.h>
#include <otf2/OTF2_Events.h>
#include <otf2/OTF2_Definitions.h>
#include <otf2/OTF2_AttributeList.h>
#include <otf2/OTF2_EvtReaderCallbacks.h>

Go to the source code of this file.

Functions
OTF2_ErrorCode	OTF2_EvtReader_GetLocationID (const OTF2_EvtReader *reader, OTF2_LocationRef *location)
	Return the location ID of the reading related location. More...
OTF2_ErrorCode	OTF2_EvtReader_GetPos (OTF2_EvtReader *reader, uint64_t *position)
	The following function can be used to get the position (number of the event in the stream) of last read event. More...
OTF2_ErrorCode	OTF2_EvtReader_SetCallbacks (OTF2_EvtReader *reader, const OTF2_EvtReaderCallbacks *callbacks, void *userData)
	Sets the callback functions for the given reader object. Every time when OTF2 reads a record, a callback function is called and the records data is passed to this function. Therefore the programmer needs to set function pointers at the "callbacks" struct for the record type he wants to read. More...
OTF2_ErrorCode	OTF2_EvtReader_Seek (OTF2_EvtReader *reader, uint64_t position)
	Seek jumps to an event position. More...
OTF2_ErrorCode	OTF2_EvtReader_ReadEvents (OTF2_EvtReader *reader, uint64_t recordsToRead, uint64_t *recordsRead)
	After callback registration, the local events could be read with the following function. Reads at most recordsToRead records. The reader indicates that it reached the end of the trace by just reading less records than requested. More...
OTF2_ErrorCode	OTF2_EvtReader_TimeStampRewrite (OTF2_EvtReader *reader, OTF2_TimeStamp time)
	The following function rewrites the timestamp from the event on the actual reading position if the buffer is in OTF2_BUFFER_MODIFY mode. It also modifies the timestamp for all other events in the same timestamp bundle. This function also has to keep track that not only the last timestamp, but all records equal to the last timestamp has to be modified. This is done by a position list, if there has no seek appeared before. In this case a position list can be easily generated because of that the reader has seen all related timestamps before. This not the case if there has a seek appeared before. In this case the related timestamp positions are generated by a linear search. More...
OTF2_ErrorCode	OTF2_EvtReader_ReadEventsBackward (OTF2_EvtReader *reader, uint64_t recordsToRead, uint64_t *recordsRead)
	This functions reads recordsRead events backwards from the current position. More...
OTF2_ErrorCode	OTF2_EvtReader_ApplyMappingTables (OTF2_EvtReader *reader, bool action)
	Enable or disable applying of the mapping tables to events read from this event reader. More...
OTF2_ErrorCode	OTF2_EvtReader_ApplyClockOffsets (OTF2_EvtReader *reader, bool action)
	Enable or disable applying of the clock offset to event timestamps read from this event reader. More...

Detailed Description

This is the local event reader, which reads events from one location.

Function Documentation

OTF2_ErrorCode OTF2_EvtReader_GetLocationID	(	const OTF2_EvtReader *	reader,
		OTF2_LocationRef *	location
	)

Return the location ID of the reading related location.

Parameters

	reader	Reader object which reads the events from its buffer.
[out]	location	ID of the location.

Returns

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

OTF2_ErrorCode OTF2_EvtReader_GetPos	(	OTF2_EvtReader *	reader,
		uint64_t *	position
	)

The following function can be used to get the position (number of the event in the stream) of last read event.

Parameters

	reader	Reader object which reads the events from its buffer.
[out]	position	Number of the event in the stream.

Returns

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

OTF2_ErrorCode OTF2_EvtReader_SetCallbacks	(	OTF2_EvtReader *	reader,
		const OTF2_EvtReaderCallbacks *	callbacks,
		void *	userData
	)

Sets the callback functions for the given reader object. Every time when OTF2 reads a record, a callback function is called and the records data is passed to this function. Therefore the programmer needs to set function pointers at the "callbacks" struct for the record type he wants to read.

These callbacks are ignored, if the events are read by an global event reader.

Parameters

reader	Reader object which reads the events from its buffer.
callbacks	Struct which holds a function pointer for each record type. OTF2_EvtReaderCallbacks_New.
userData	Data passed as argument userData to the record callbacks.

Returns

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

OTF2_ErrorCode OTF2_EvtReader_Seek	(	OTF2_EvtReader *	reader,
		uint64_t	position
	)

Seek jumps to an event position.

Parameters

reader	Reader object which reads the events from its buffer.
position	Number of the event, where the reader has to jump.

Returns

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

OTF2_ErrorCode OTF2_EvtReader_ReadEvents	(	OTF2_EvtReader *	reader,
		uint64_t	recordsToRead,
		uint64_t *	recordsRead
	)

After callback registration, the local events could be read with the following function. Reads at most recordsToRead records. The reader indicates that it reached the end of the trace by just reading less records than requested.

Parameters

	reader	Reader object which reads the events from its buffer.
	recordsToRead	How many records can be read next.
[out]	recordsRead	Return how many records where really read.

Returns

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

OTF2_ErrorCode OTF2_EvtReader_TimeStampRewrite	(	OTF2_EvtReader *	reader,
		OTF2_TimeStamp	time
	)

The following function rewrites the timestamp from the event on the actual reading position if the buffer is in OTF2_BUFFER_MODIFY mode. It also modifies the timestamp for all other events in the same timestamp bundle. This function also has to keep track that not only the last timestamp, but all records equal to the last timestamp has to be modified. This is done by a position list, if there has no seek appeared before. In this case a position list can be easily generated because of that the reader has seen all related timestamps before. This not the case if there has a seek appeared before. In this case the related timestamp positions are generated by a linear search.

Parameters

reader	Reader object which reads the events from its buffer.
time	New timestamp

Returns

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

OTF2_ErrorCode OTF2_EvtReader_ReadEventsBackward	(	OTF2_EvtReader *	reader,
		uint64_t	recordsToRead,
		uint64_t *	recordsRead
	)

This functions reads recordsRead events backwards from the current position.

Parameters

	reader	Reader object which reads the events from its buffer.
	recordsToRead	How many records can be read next.
[out]	recordsRead	Return how many records where really read.

Returns

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

OTF2_ErrorCode OTF2_EvtReader_ApplyMappingTables	(	OTF2_EvtReader *	reader,
		bool	action
	)

Enable or disable applying of the mapping tables to events read from this event reader.

This setting has no effect if the events are read by an global event reader.

Parameters

reader	Reader object.
action	Truth value whether the mappings should be applied or not.

Returns

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

OTF2_ErrorCode OTF2_EvtReader_ApplyClockOffsets	(	OTF2_EvtReader *	reader,
		bool	action
	)

Enable or disable applying of the clock offset to event timestamps read from this event reader.

This setting has no effect if the events are read by an global event reader.

Parameters

reader	Reader object.
action	Truth value whether the clock offsets should be applied or not.

Returns

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