Describes the handler functions for a dynamic stream. More...

#include <SimuTraceTypes.h>

Data Fields
DynamicStreamInitialize	initialize
	Pointer to stream initializer. This handler is optional and may be left `NULL`.

DynamicStreamFinalize	finalize
	Pointer to stream finalizer. This handler is optional and my be left `NULL`.

DynamicStreamOpen	open
	Pointer to stream open handler. This handler is optional and may be left `NULL`.

DynamicStreamClose	close
	Pointer to stream handle close handler. This handler is optional and may be left `NULL`.

DynamicStreamGetNextEntry	getNextEntry
	Pointer to entry delivery handler. This handler is mandatory.

void *	reserved [4]
	Reserved for future use. Leave `NULL`.

Related Functions
(Note that these are not member functions.)
typedef int(*	DynamicStreamInitialize) (const DynamicStreamDescriptor descriptor, StreamId id, void *userData)
	Dynamic stream initializer. More...

typedef void(*	DynamicStreamFinalize) (StreamId id, void *userData)
	Dynamic stream finalizer. More...

typedef int(*	DynamicStreamOpen) (const DynamicStreamDescriptor descriptor, StreamId id, QueryIndexType type, uint64_t value, StreamAccessFlags flags, void *userDataOut)
	Dynamic stream open handler. More...

typedef void(*	DynamicStreamClose) (StreamId id, void **userData)
	Dynamic stream handle close handler. More...

typedef int(*	DynamicStreamGetNextEntry) (void userData, void *entryOut)
	Dynamic stream entry delivery handler. More...

Detailed Description

Dynamic streams are operated by user-defined handlers. This descriptor should be filled with pointers to the various functions. These functions are called by Simutrace to, for example, dynamically create entries or perform setup and cleanup for the stream.

Since: 3.2

Friends And Related Function Documentation

typedef int(* DynamicStreamInitialize) (const DynamicStreamDescriptor *descriptor, StreamId id, void **userData)

This dynamic stream handler is responsible for the initialization of any user implementation specific data and dependencies for the dynamic stream. This handler is called once when the stream is registered.

Parameters

descriptor	The descriptor handed to Simutrace for stream registration.
id	The id of the new dynamic stream.
userData	Pointer to the DynamicStreamDescriptor::userData field. The handler may change the user-defined per-stream data by setting a new value with this parameter.

Returns: The handler should return 0 on success or any other value otherwise. The return value is then interpreted as error code, the stream registration is aborted and the error code can be retrieved through StGetLastError().

Warning: Calling into the Simutrace API from within the handler (e.g., to register or open another stream) is undefined behavior and must be avoided. If such operations are required consider moving them into the stream open callback (DynamicStreamOperations::open) or perform them prior to the dynamic stream registration. Results from the operations can be passed to this handler via the DynamicStreamDescriptor::userData field.

Remarks: The handler does not need to be thread-safe in the context of a single session.

Since: 3.2

typedef void(* DynamicStreamFinalize) (StreamId id, void *userData)

This dynamic stream handler is responsible for cleaning up any user-defined data that has been allocated for the stream. The handler is called once, when the stream is destroyed (e.g., when the store closes).

Parameters

id	The id of the dynamic stream that is closed.
userData	Pointer to the user-defined stream data. This is the DynamicStreamDescriptor::userData field. The handler should free any resources associated with the user data.

Warning: Calling into the Simutrace API from within the handler (e.g., to register or open another stream) is undefined behavior and must be avoided.

Remarks: The handler does not need to be thread-safe in the context of a single session.

Since: 3.2

typedef int(* DynamicStreamOpen) (const DynamicStreamDescriptor *descriptor, StreamId id, QueryIndexType type, uint64_t value, StreamAccessFlags flags, void **userDataOut)

This dynamic stream handler is responsible for performing any operations that are necessary to get data from the stream later. The handler is invoked in the context of a call to StStreamOpen(). The handler may initialize user-defined data that will be local to the stream handle that is created during the open operation.

The dynamic stream should adhere to the semantic of the type, value, and flags parameters as defined for regular streams. If a combination of flags is not supported, an error should be returned.

Parameters

descriptor	The descriptor of the stream for which the handle is to be created.
id	The id of the dynamic stream.
type	Type of property value. Contains the value passed to StStreamOpen().
value	A value used in the query. Contains the value passed to StStreamOpen().
flags	Supplies information on how the caller intends to access the stream. Contains the value passed to StStreamOpen().
userDataOut	A dynamic stream handle can reference arbitrarily user-defined data, which will be available in all handlers that operate on the handle (e.g., DynamicStreamGetNextEntry). The parameter receives a pointer to the data and may be left `NULL` if not required. If the dynamic stream uses per-handle user-defined data, the data must only be released in DynamicStreamOperations::close.

Returns: The handler should return 0 on success or any other value otherwise. The return value is then interpreted as error code, the handle creation is aborted and the error code can be retrieved through StGetLastError().

Remarks: The handler does not need to be thread-safe in the context of a single stream, but it can be called in parallel for different streams.

Since: 3.2

typedef void(* DynamicStreamClose) (StreamId id, void **userData)

Parameters

id	Id of the stream that is closed.
userData	Pointer to the user data of the handle. Handle local data should be released in this function and the variable pointer to by userData should be set to `NULL`.

Remarks: Note that after this call, there might be further open handles to the stream. To release any data shared by all handles, you have to implement some sort of reference counting or place shared data in the per-stream user-defined data (see DynamicStreamInitialize).; The handler does not need to be thread-safe in the context of a single stream, but it can be called in parallel for different streams.

Since: 3.2

typedef int(* DynamicStreamGetNextEntry) (void *userData, void **entryOut)

Parameters

userData	Pointer to any user-defined data supplied by the open handler DynamicStreamOperations::open.
entryOut	Pointer that should be set to the location of the entry to be returned. The entry must be of the type and size specified in the stream descriptor for the dynamic stream. The returned value may be `NULL`, to indicate the end of the stream. It must be `NULL` if an error is returned.

Returns: The handler should return 0 on success or any other value otherwise. The return value is then interpreted as error code, the handle creation is aborted and the error code can be retrieved through StGetLastError().

Remarks: If the handler should return entries of different type, consider using a meta entry, which only specifies the type and storage location of the real entry. Then let the handler always return the meta entry, instead of the real entry.; The entry does not have to be available beyond the next call to this handler or a close with DynamicStreamOperations::close. The handler therefore might use a single per-handle entry, which is updated and returned on each call (effectively always returning the same pointer).; To indicate the end of the stream, return 0 and set entryOut to NULL.; The handler does not need to be thread-safe in the context of a single stream, but it can be called in parallel for different streams.

Since: 3.2

The documentation for this struct was generated from the following file:

SimuTraceTypes.h

Data Fields

Related Functions

Detailed Description

Friends And Related Function Documentation