#include "SimuTraceTypes.h"
#include "SimuTraceEntryTypes.h"

Functions
SIMUTRACE_API uint32_t	StGetClientVersion (void)
	Version of the Simutrace client. More...

SIMUTRACE_API int	StGetLastError (ExceptionInformation *informationOut)
	Returns the last exception. More...

SIMUTRACE_API void	StSetLastError (ExceptionClass type, int code, const char *message)
	Sets the last exception. More...

SIMUTRACE_API SessionId	StSessionCreate (const char *server)
	Creates a new session. More...

SIMUTRACE_API _bool	StSessionOpen (SessionId session)
	Opens an existing local session. More...

SIMUTRACE_API _bool	StSessionClose (SessionId session)
	Closes an open session. More...

SIMUTRACE_API _bool	StSessionCreateStore (SessionId session, const char *specifier, _bool alwaysCreate)
	Creates a new store. More...

SIMUTRACE_API _bool	StSessionOpenStore (SessionId session, const char *specifier)
	Opens an existing store. More...

SIMUTRACE_API _bool	StSessionCloseStore (SessionId session)
	Closes a session's store. More...

SIMUTRACE_API _bool	StSessionSetConfiguration (SessionId session, const char *configuration)
	Sets session configurations. More...

SIMUTRACE_API _bool	StMakeStreamDescriptor (const char name, uint32_t entrySize, StreamTypeFlags flags, StreamDescriptor descOut)
	Creates a new stream descriptor. More...

SIMUTRACE_API _bool	StMakeStreamDescriptorFromType (const char name, const StreamTypeDescriptor type, StreamDescriptor *descOut)
	Creates a new stream descriptor from existing type information. More...

SIMUTRACE_API const StreamTypeDescriptor *	StStreamFindMemoryType (ArchitectureSize size, MemoryAccessType accessType, MemoryAddressType addressType, _bool hasData)

SIMUTRACE_API _bool	StMakeStreamDescriptorDynamic (const char name, uint32_t entrySize, StreamTypeFlags flags, const void userData, const DynamicStreamOperations operations, DynamicStreamDescriptor descOut)
	Creates a new stream descriptor for a dynamic stream. More...

SIMUTRACE_API _bool	StMakeStreamDescriptorDynamicFromType (const char name, const void userData, const StreamTypeDescriptor type, const DynamicStreamOperations operations, DynamicStreamDescriptor *descOut)
	Creates a new stream descriptor for a dynamic stream from exisiting type information. More...

SIMUTRACE_API StreamId	StStreamRegister (SessionId session, StreamDescriptor *desc)
	Registers a new stream. More...

SIMUTRACE_API StreamId	StStreamRegisterDynamic (SessionId session, DynamicStreamDescriptor *desc)
	Registers a new dynamic stream. More...

SIMUTRACE_API int	StStreamEnumerate (SessionId session, size_t bufferSize, StreamId *streamIdsOut)
	Returns a list of all registered streams. More...

SIMUTRACE_API _bool	StStreamQuery (SessionId session, StreamId stream, StreamQueryInformation *informationOut)
	Returns detailed information on a stream. More...

SIMUTRACE_API StreamHandle	StStreamAppend (SessionId session, StreamId stream, StreamHandle handle)
	Opens a stream for appending write access. More...

SIMUTRACE_API StreamHandle	StStreamOpen (SessionId session, StreamId stream, QueryIndexType type, uint64_t value, StreamAccessFlags flags, StreamHandle handle)
	Opens a stream for read access. More...

SIMUTRACE_API _bool	StStreamClose (StreamHandle handle)
	Closes a handle to a stream. More...

static void *	StGetNextEntryFast (StreamHandle *handlePtr)
	Returns a pointer to the next entry in a stream. More...

SIMUTRACE_API void *	StGetNextEntry (StreamHandle *handlePtr)
	Returns a pointer to the next entry in a stream. More...

static void *	StGetPreviousEntryFast (StreamHandle *handlePtr)
	Returns a pointer to the previous entry in a stream. More...

SIMUTRACE_API void *	StGetPreviousEntry (StreamHandle *handlePtr)
	Returns a pointer to the previous entry in a stream. More...

static void	StSubmitEntryFast (StreamHandle handle)
	Completes an entry. More...

SIMUTRACE_API void	StSubmitEntry (StreamHandle handle)
	Completes an entry. More...

SIMUTRACE_API size_t	StWriteVariableData (StreamHandle handlePtr, byte sourceBuffer, size_t sourceLength, uint64_t *referenceOut)
	Writes variable-sized data to a stream. More...

SIMUTRACE_API size_t	StReadVariableData (StreamHandle handlePtr, uint64_t reference, byte destinationBuffer)
	Reads variable-sized data. More...

Variables
SIMUTRACE_API const uint32_t	StClientVersion
	Version of the Simutrace client. More...

Function Documentation

SIMUTRACE_API uint32_t StGetClientVersion ( void )

Wrapper function to receive the client version. See StClientVersion for more information.

Since: 3.1

See also: StClientVersion

SIMUTRACE_API int StGetLastError ( ExceptionInformation * informationOut )

Returns extended exception information on the last error during a Simutrace API call.

Parameters

informationOut A pointer to an ExceptionInformation structure that will receive the error information. The parameter is optional and may be NULL. Freeing the message member in the structure is not necessary, however the string will only be valid until the next API call.

Returns: The last error code. For platform exceptions this is the operating system error code.

Remarks: The exception information is thread local. StGetLastError() thus always returns error information on API calls from the calling thread only.

Since: 3.0

SIMUTRACE_API void StSetLastError	(	ExceptionClass	type,
		int	code,
		const char *	message
	)

Sets the last error information for the calling thread. The value can be retrieved with StGetLastError().

Parameters

type	The type of the exception, which determines how to interpret the error code. Set this to EcUser for user-defined error codes.
code	One of the pre-defined error codes or a user-defined one, depending on the exception type.
message	Optional pointer to an error message. This parameter can be `NULL`.

Remarks: The exception information is thread local. StSetLastError() thus always sets error information for the calling thread only.

Since: 3.2

See also: RuntimeException; NetworkException

SIMUTRACE_API SessionId StSessionCreate ( const char * server )

Connections of a client to a Simutrace storage server are represented as a session. This method connects to the specified server and creates a new local session as well as a new session on the server side. Calling this function is the first step, when working with Simutrace. To successfully establish a connection, the server process must already be running and accept connections on the address specified by server.

Parameters

server

Specifies the connection string used to contact the server. The specifier must be supplied in the form channel:address. Supported specifiers are:

local:pipe (recommended)

The server runs on the same host as the client. This is the fastest connection with a Simutrace server, because the server and client can use shared memory to communicate trace data. To exchange commands a named pipe is utilized. The named pipe must be set in the server configuration and will be created by the server at startup.

Example connecting through a named pipe to a server running on the same host. On Windows, the "\\.\Pipe\"- prefix must be omitted.
1 local:/tmp/mypipe
socket:ipv4|[ipv6]|dns:port

The server runs on a remote host. This channel will use a regular TCP/IP connection. The remote host may be specified through its IPv4, IPv6 or its dns name. Since Simutrace does not have a default port, the address must always include the destination port. The socket connection can also be used to connect to a local server, however in that case a local channel connection is recommended to improve performance.

Examples connecting through a TCP socket to a server running on the same or a remote host.
1 socket:10.1.1.10:7000

2 socket:simutrace.org:7000

3 socket:[2001:0db8:0000:0000:0000:ff00:0042:8329]:7000

When setting up a socket binding in the server the binding string may also contain a "*"-wildcard for (a) the interface address to denote all installed interfaces, and (b) for the port number to let the operating system choose a port. However, keep in mind that you need to specify the exact address and port on the client. Examples:
1 socket:*:7000

2 socket:*:*

3 socket:10.1.1.10:*

Returns: A SessionId, identifying the newly created session if successful, INVALID_SESSION_ID otherwise. For a more detailed error description call StGetLastError().

Remarks: The connection to the server is established by the thread calling StSessionCreate(). Only the very same thread is able to work with the session. To connect further threads to a session call StSessionOpen() from within the respective threads that should participate in the tracing session.; Before a thread connected to a Simutrace server exits, it must release its connection. For more details see StSessionClose().

Since: 3.0

See also: StSessionOpen(); StSessionClose()

SIMUTRACE_API _bool StSessionOpen ( SessionId session )

Each thread that wants to participate in a tracing session (e.g., read or write data via the tracing API), must be connected to a session. This method connects a thread to an existing local session.

Parameters

session The id of the session to be opened as originally returned by StSessionCreate().

Returns: _true if successful, _false otherwise. For a more detailed error description call StGetLastError().

Remarks: A thread may not connect to a session created in a different process or on a remote host running the Simutrace client. A session is always process local and thus accessible for threads of the same process only. To share a tracing session between multiple processes or hosts, create a new session and open the same store in/on all processes/machines. For more details see StSessionCreateStore().; Before a thread connected to a Simutrace server exits, it must release its connection. For more details see StSessionClose().

Since: 3.0

See also: StSessionCreate(); StSessionClose()

SIMUTRACE_API _bool StSessionClose ( SessionId session )

This method closes a thread's reference to an open session. If this is the last reference, the session is run down. After closing the session, the executing thread may connect to a different session again.

Parameters

session The id of the session to be closed as originally returned by StSessionCreate().

Returns: _true if successful, _false otherwise. For a more detailed error description call StGetLastError().

Remarks: Before a thread connected to a Simutrace server exits, it must call StSessionClose() to release its connection. A session is automatically closed as soon as the last reference is closed, that is all threads participating in a session have called StSessionClose(). If a thread fails to do so, the connection and hence the session is dangling until the client application terminates. If the connection to the server is lost (e.g., due to a network failure), the server treats this as an implicit close and, if all connections are lost, frees the session. If the client program terminates without closing its open sessions, the server will treat this as a loss of all connections and consequently close the corresponding sessions.; Closing a session will also close its reference to the open store (if any). For more details about closing a store and the effects, see StSessionCloseStore().

Since: 3.0

See also: StSessionCreate(); StSessionOpen()

SIMUTRACE_API _bool StSessionCreateStore	(	SessionId	session,
		const char *	specifier,
		_bool	alwaysCreate
	)

A store is the data back-end for a Simutrace tracing session. All trace data recorded or read in a session is stored in the currently open store. Creating or opening a store is thus typically the next operation after creating a new session. This method creates a new store.

Parameters

session	The id of the session to open a store in as originally returned by StSessionCreate().
specifier	Simutrace comes with a modular storage back-end that can employ custom trace formats to save trace data. The specifier must be supplied in the form `format:path`. Supported specifiers are: `simtrace:path` (recommended) Simutrace's native storage format (v 3.0). It fully supports all features, provides fast access even for very large traces and comes with a built-in aggressive but fast compressor for memory traces (see StStreamFindMemoryType()). The `simtrace` storage back-end saves trace data in a regular file on disk. The path can be absolute (e.g., `C:\simutrace\traces\mytrace.sim` in Windows or `/traces/mytrace.sim` in Linux) or a relative path. Relative paths use the configured root for the `simtrace` storage format (`store.simtrace.root`) or the active workspace (`server.workspace`) as base path. For more For more information on how to configure these settings see StSessionSetConfiguration() and the sample server configuration file. The `simtrace` storage format uses the extension `sim`. Although a trace can have any valid file name, enumerating `simtrace` stores will list only files with the `sim` extension. Example creating a store using a relative path. 1 simtrace:mytrace.sim The `simtrace` format is the only supported format in this release. This may change in the future.
alwaysCreate	Indicates if the store should be overwritten, if it already exists.

Returns: _true if successful, _false otherwise. For a more detailed error description call StGetLastError().

Remarks: A store may receive new data only directly after its creation. Closing a store marks it read-only, denying any modification afterwards. This may change in the future.; Simutrace uses a global store concept, where the same store may be open in multiple sessions (in the same server). This allows writing to and reading from the same trace file from different processes or physical machines (each one having its own session). Calling this method with alwaysCreate set to _true will fail if the store is still open in another session.

Warning: Be sure to set the alwaysCreate parameter as intended to avoid data loss. Simutrace won't present a confirmation before deleting an existing store!

Deprecated:: Before 3.1: If alwaysCreate was set to _false and the store already existed, this method was used to open a store. The method now fails in this scenario. Use StSessionOpenStore() instead.

Since: 3.0

See also: StSessionCloseStore(); StSessionSetConfiguration()

SIMUTRACE_API _bool StSessionOpenStore	(	SessionId	session,
		const char *	specifier
	)

A store is the data back-end for a Simutrace tracing session. All trace data recorded or read in a session is stored in the currently open store. Creating or opening a store is thus typically the next operation after creating a new session. This method opens an existing store.

Parameters

session	The id of the session to open a store in as originally returned by StSessionCreate().
specifier	Simutrace comes with a modular storage back-end that can employ custom trace formats to save trace data. The specifier must be supplied in the form `format:path`. For more information on storage specifier please refer to StSessionCreateStore().

Returns: _true if successful, _false otherwise. For a more detailed error description call StGetLastError().

Remarks: A store may receive new data only directly after its creation. Closing a store marks it read-only, denying any modification afterwards. This may change in the future.

Since: 3.1

See also: StSessionCreateStore(); StSessionCloseStore()

SIMUTRACE_API _bool StSessionCloseStore ( SessionId session )

Each session may have only one store open at a time. Use this function to close the currently open store. This allows you to switch to a different store without creating a new session.

Parameters

session The id of the session whose store should be closed as originally returned by StSessionCreate().

Returns: _true if successful, _false otherwise. For a more detailed error description call StGetLastError().

Remarks: Simutrace uses a global store concept, where the same store may be open in multiple sessions (in the same server). This allows writing to and reading from the same trace file from different processes or physical machines (each one having its own session). Closing a session's reference to a store will only effectively close the store, if this is the last reference.; A session closes its reference to a store automatically when the session itself is closed.; Closing a store will implicitly close all handles to streams of this store. For more details on closing stream handles and the effects see StStreamClose().

Since: 3.0

See also: StSessionCreateStore()

SIMUTRACE_API _bool StSessionSetConfiguration	(	SessionId	session,
		const char *	configuration
	)

This method allows configuring various parameters for the specified session. For a reference of all configurable parameters see the sample server configuration file, which comes with Simutrace.

Parameters

session	The id of the session to be configured as originally returned by StSessionCreate().
configuration	A string describing the configuration to set. For information on the format see the documentation of libconfig.

Returns: _true if successful, _false otherwise. For a more detailed error description call StGetLastError().

Remarks: The Simutrace storage server has a main configuration, which can be set by specifying a configuration file or by supplying command line parameters when starting the server executable. The server replicates its entire configuration when it creates a new session in behalf of the user. This method allows modifying the session configuration. The underlying server configuration cannot be changed with this method.

Since: 3.0

SIMUTRACE_API _bool StMakeStreamDescriptor	(	const char *	name,
		uint32_t	entrySize,
		StreamTypeFlags	flags,
		StreamDescriptor *	descOut
	)

This method is a helper function to quickly create a stream description needed to register a new stream. The description contains information about the stream's name and layout of trace entries, that is records written to or read from a stream.

Parameters

name	A friendly name of the new stream (e.g., "CPU Memory Accesses").
entrySize	The size of a single trace entry in bytes. To specify a variable-sized entry type, use makeVariableEntrySize().
flags	Supplies the flags used for the type of the new stream.
descOut	Pointer to a StreamDescriptor structure that will receive the new stream information.

Returns: _true if successful, _false otherwise. For a more detailed error description call StGetLastError().

Remarks: Simutrace internally identifies entry types through a StreamTypeId. This method will generate a random id on every call. Using type information generated by this method is thus not recommended if a constant id is required, for example to find a certain stream of data by type when opening an existing store.; Simutrace uses a stream's type information to find an appropriate encoder. The encoder processes (usually compresses) the data in a stream before it is written to disk. To utilize the built-in memory trace encoder use StStreamFindMemoryType() and StMakeStreamDescriptorFromType().

Deprecated:: Before 3.2: temporalOrder was the only flag that could be specified. The parameter has been replaced.

Since: 3.0

See also: StMakeStreamDescriptorFromType(); StStreamRegister()

SIMUTRACE_API _bool StMakeStreamDescriptorFromType	(	const char *	name,
		const StreamTypeDescriptor *	type,
		StreamDescriptor *	descOut
	)

This method is a helper function to quickly create a stream description needed to register a new stream. The description contains information about the stream's name and layout of trace entries, that is records written to or read from a stream. This method uses the supplied type information.

Parameters

name	A friendly name of the new stream (e.g., "CPU Memory Accesses").
type	Pointer to a valid StreamTypeDescriptor structure, defining the desired type of the new stream.
descOut	Pointer to a StreamDescriptor structure that will receive the new stream information.

Returns: _true if successful, _false otherwise. For a more detailed error description call StGetLastError().

Remarks: Simutrace uses a stream's type information to find an appropriate encoder. The encoder processes (usually compresses) the data in a stream before it is written to disk. To utilize the built-in memory trace encoder get the type by calling StStreamFindMemoryType().

Since: 3.0

See also: StStreamFindMemoryType(); StMakeStreamDescriptor(); StStreamRegister()

SIMUTRACE_API const StreamTypeDescriptor* StStreamFindMemoryType	(	ArchitectureSize	size,
		MemoryAccessType	accessType,
		MemoryAddressType	addressType,
		_bool	hasData
	)

Returns stream descriptions for built-in memory entry types

Simutrace comes with an integrated aggressive, but fast compressor for memory traces. To utilize the compressor, the stream must use one of the types returned by this method and employ the simtrace storage format (see StSessionCreateStore()).

Parameters

size	Architecture size of the simulated system.
accessType	Type of memory operations that the new stream should hold.
addressType	The semantic of the address field.
hasData	Indicates if the memory entry will contain the data read or written with the memory entry.

Returns: Stream descriptor identifying the desired memory entry type. Do not modify the returned stream descriptor.

Remarks: The memory trace compressor makes heavy use of the server's internal memory pool. For example to compress a 64 MiB segment of raw memory references (DataWrite64), the server may allocate over 1 GiB of additional internal pool memory. When reading a memory stream with read-ahead active, the amount of consumed memory increases. Ensure you run the server with enough pool memory configured.

Since: 3.0

See also: StMakeStreamDescriptor(); StStreamRegister()

SIMUTRACE_API _bool StMakeStreamDescriptorDynamic	(	const char *	name,
		uint32_t	entrySize,
		StreamTypeFlags	flags,
		const void *	userData,
		const DynamicStreamOperations *	operations,
		DynamicStreamDescriptor *	descOut
	)

This method is a helper function to quickly create dynamic stream descriptions needed to register a new dynamic stream. The descriptions contains information about the stream's name, layout, and operations.

Parameters

name	A friendly name of the new stream (e.g., "Filtered memory accesses").
entrySize	The size of a single trace entry in bytes. Variable-sized entries are not supported.
flags	Supplies the flags used for the type of the new stream.
userData	A pointer to optional user-defined data that should be available when the stream is opened. The data must not be freed for the lifetime of the stream.
operations	Pointer to a set of operations that implement the logic of the dynamic stream.
descOut	Pointer to a DynamicStreamDescriptor structure that will receive the new stream information.

Returns: _true if successful, _false otherwise. For a more detailed error description call StGetLastError().

Since: 3.2

See also: StMakeStreamDescriptorDynamicFromType(); StStreamRegisterDynamic()

SIMUTRACE_API _bool StMakeStreamDescriptorDynamicFromType	(	const char *	name,
		const void *	userData,
		const StreamTypeDescriptor *	type,
		const DynamicStreamOperations *	operations,
		DynamicStreamDescriptor *	descOut
	)

This method is a helper function to quickly create dynamic stream descriptions needed to register a new dynamic stream. The descriptions contains information about the stream's name, layout, and operations. This method uses the supplied type information.

Parameters

name	A friendly name of the new stream (e.g., "Filtered memory accesses").
type	Pointer to a valid StreamTypeDescriptor structure, defining the desired type of the new stream.
userData	A pointer to optional user-defined data that should be available when the stream is opened. The data must not be freed for the lifetime of the stream.
operations	Pointer to a set of operations that implement the logic of the dynamic stream.
descOut	Pointer to a DynamicStreamDescriptor structure that will receive the new stream information.

Returns: _true if successful, _false otherwise. For a more detailed error description call StGetLastError().

Since: 3.2

See also: StMakeStreamDescriptorDynamic(); StStreamRegisterDynamic()

SIMUTRACE_API StreamId StStreamRegister	(	SessionId	session,
		StreamDescriptor *	desc
	)

Streams are the basic interface to write or read data with Simutrace. Streams always belong to a store. This method registers a new stream in the session's active store. Before doing so, the caller must initially create a new store with StSessionCreateStore().

Parameters

session	The id of the session, whose store should register the stream.
desc	Pointer to a stream descriptor defining the properties of the new stream (e.g., the desired type of data entries). To create a descriptor see StMakeStreamDescriptor() or StMakeStreamDescriptorFromType().

Returns: The id of the new stream if successful, INVALID_STREAM_ID otherwise. For a more detailed error description call StGetLastError().

Remarks: Registering streams is only possible for newly created stores. This may change in the future.; When opening an existing store, Simutrace automatically restores all streams under the same ids. To retrieve a list of all registered stream call StStreamEnumerate().

Warning: Once a stream is registered, it cannot be removed. The operation is irreversible.

Since: 3.0

See also: StMakeStreamDescriptor(); StMakeStreamDescriptorFromType(); StStreamEnumerate(); StStreamQuery()

SIMUTRACE_API StreamId StStreamRegisterDynamic	(	SessionId	session,
		DynamicStreamDescriptor *	desc
	)

Streams are the basic interface to work with data in Simutrace. Dynamic streams differ from regular streams in that entries are created dynamically by user-defined handler functions. This way multiplexers, filters, etc. can be realized. A filter, for example, may connect to a regular static stream and pass only those entries that meet certain criteria. Accessing the resulting dynamic stream does not differ from regular streams. Dynamic streams therefore may be used as input for other dynamic streams, building a cascade of stream processors.

Parameters

session	The id of the session, whose store should register the stream.
desc	Pointer to a dynamic stream descriptor defining the properties of the new dynamic stream (e.g., the desired type of data entries). To create a dynamic descriptor see StMakeStreamDescriptorDynamic() or StMakeStreamDescriptorDynamicFromType().

Returns: The id of the new dynamic stream if successful, INVALID_STREAM_ID otherwise. For a more detailed error description call StGetLastError().

Remarks: Dynamic streams are not persistent. They are lost when the session is closed.; Dynamic streams are visible only within the same local session.

Warning: Once a stream is registered, it cannot be removed. The operation is irreversible.

Since: 3.2

See also: StMakeStreamDescriptorDynamic(); StMakeStreamDescriptorDynamicFromType(); StStreamEnumerate(); StStreamQuery()

SIMUTRACE_API int StStreamEnumerate	(	SessionId	session,
		size_t	bufferSize,
		StreamId *	streamIdsOut
	)

After registering streams or opening an existing store, all streams are available through their corresponding ids. This method enumerates all registered streams by returning a list of valid stream ids. To get information on a certain stream call StStreamQuery().

Parameters

session	The id of the session to enumerate all streams from.
bufferSize	Total size in bytes of the buffer supplied to receive the stream ids. If the buffer is too small, it will receive as many ids as fit.
streamIdsOut	Supplies the destination buffer, which receives the list of stream ids. Each element in the buffer will be of type StreamId. The buffer must be at least `bufferSize` bytes in size.

Returns: The number of valid stream ids, that is registered streams. The method will return -1 on error. For a more detailed error description call StGetLastError().

Remarks: To determine the correct size for the destination buffer, call this method with bufferSize and streamIdsOut set to 0 and NULL respectively. The return value indicates the number of stream ids (StreamId) the buffer must be able to accommodate.; The return value is always the number of registered streams, not the number of ids copied to the buffer.

Deprecated:: Before 3.2: The method fails if the given buffer is too small to receive all stream ids.

Since: 3.0

See also: StStreamRegister(); StStreamQuery()

SIMUTRACE_API _bool StStreamQuery	(	SessionId	session,
		StreamId	stream,
		StreamQueryInformation *	informationOut
	)

This method returns detailed information on the properties of a stream. The information includes the StreamDescriptor originally supplied to create the stream as well as a set of statistics such as the compressed size of the stream. See StreamQueryInformation for furthers details.

Parameters

session	The id of the session that holds the stream of interest.
stream	The id of the stream to query.
informationOut	A pointer to a StreamQueryInformation structure which will receive the stream information.

Returns: _true if successful, _false otherwise. For a more detailed error description call StGetLastError().

Since: 3.0

See also: StStreamRegister(); StStreamEnumerate()

SIMUTRACE_API StreamHandle StStreamAppend	(	SessionId	session,
		StreamId	stream,
		StreamHandle	handle
	)

This method opens a write handle to the specified stream. The handle can be used with StGetNextEntryFast() to append new entries to a stream.

Parameters

session	The id of the session that holds the stream of interest. Must be `INVALID_SESSION_ID`, when supplying `handle`.
stream	The id of the stream to open a handle for. Must be `INVALID_STREAM_ID`, when supplying `handle`.
handle	Existing write handle to the same stream, which will be used for the request. Leave this parameter `NULL`.

Returns: A write handle to the specified stream if successful, NULL otherwise. For a more detailed error description call StGetLastError().

Remarks: While each stream may have multiple independent read handles, a stream may have only one write handle. If the caller already created the write handle and it is still open, it must be passed with handle.; Use this method only to create an initial write handle to a stream, that is supply the session and stream parameters and set handle to NULL. StGetNextEntryFast() will take care of proceeding the handle along the stream.; Writing to a stream at arbitrary positions is not supported. Entries can only be appended to a stream.; Use StStreamClose() to close the write handle at the end of the tracing session. It is valid to create a new write handle afterwards, as long as the store has not been closed and re-opened in the mean time.

Warning: Do not attempt to append a stream after opening an existing store. The data will be lost. This may change in the future.

Since: 3.0

See also: StStreamRegister(); StStreamOpen(); StStreamClose()

SIMUTRACE_API StreamHandle StStreamOpen	(	SessionId	session,
		StreamId	stream,
		QueryIndexType	type,
		uint64_t	value,
		StreamAccessFlags	flags,
		StreamHandle	handle
	)

This method opens a new read handle to the specified stream. The handle can be used with StGetNextEntryFast() and StGetPreviousEntryFast() to read entries.

Parameters

session	The id of the session that holds the stream of interest. Must be `INVALID_SESSION_ID`, when supplying `handle`.
stream	The id of the stream to open a handle for. Must be `INVALID_STREAM_ID`, when supplying `handle`.
type	Type of property value that indicates which position in the stream should be opened. For further information on the possible query types see QueryIndexType.
value	A value used in the query specified by `type`. See QueryIndexType for more details.
flags	Supplies information on how the caller intends to access the stream with the requested handle. For more information see StreamAccessFlags. If `handle` is supplied and `flags` is set to `StreamAccessFlags::SafNone`, the flags are taken from the handle.
handle	An existing read handle to the same stream, which will be reused for the request. Leave this parameter `NULL`.

Returns: A read handle to the specified stream if successful, NULL otherwise (if handle has been specified, an invalidated version of the handle will be returned). For a more detailed error description call StGetLastError().

The method returns a RteNotFoundException, when the supplied query did not deliver any results and the target element or area in the stream could not be identified. Note that stream segments are only visible to a query after the processing by the server has been completed!. For that reason you may encounter a RteNotFoundException for stream elements that were only recently send to the server. Queries working on sequence numbers return an RteOperationInProgressException in that case.

If successful, the handle will point to the exact entry requested by the <type, value>-pair.

Remarks: A stream may have an arbitrary number of open stream handles.; Do not attempt to write data with a handle received from this method. The data will be lost.; Use this method only to create an initial read handle to a stream, that is supply the session and stream parameters and set handle to NULL. StGetNextEntryFast() and StGetPreviousEntryFast() will take care of proceeding the handle along the stream.

Deprecated:: Before 3.1: If successful, the handle will NOT point to the exact entry requested by the <type, value>-pair. The method only guarantees that the requested entry is in the data delivered by the server for this request. To find the desired entry, use StGetNextEntryFast() on the returned handle and scan over the entries manually.

Deprecated:: Before 3.2: handle may also be a write handle to the stream.

Since: 3.0

See also: StStreamRegister(); StStreamAppend(); StStreamClose(); StGetNextEntry(); StGetPreviousEntry()

SIMUTRACE_API _bool StStreamClose ( StreamHandle handle )

This method closes the supplied stream handle.

Parameters

handle The handle to be closed.

Returns: _true if successful, _false otherwise. For a more detailed error description call StGetLastError().

Remarks: When closing a write handle, the client will automatically pass any pending new entries to the server. This will persist the entries in the open store.; Failing to explicitly call this method can lead to data loss for remote clients. While local clients use shared memory to communicate new data to the server, remote clients (i.e., socket connections) have to actively send new data to the server.; Simutrace will close all handles when the active session or store is closed.

Since: 3.0

See also: StStreamAppend(); StStreamOpen()

static void* StGetNextEntryFast ( StreamHandle * handlePtr )

inlinestatic

This method moves the read/write pointer of the supplied handle to the next entry in the stream. The pointer returned by this method can be used to write or read (depending on the handle) a single trace entry.

Parameters

handlePtr A pointer to the stream handle. The method may allocate a new handle and update the supplied pointer.

Returns: A pointer to the next trace entry if successful, NULL otherwise. For a more detailed error description call StGetLastError(). On error, the supplied handle will be invalidated. In contrast to a closed handle (see StStreamClose()), an invalidated handle is not freed and may be used to retry the operation. If successful, the caller must cast the pointer to the data type (e.g., DataWrite64) for the type supplied at stream registration.

Remarks: This method is not thread-safe when operating on the same handle.; When writing a new entry, call StSubmitEntryFast() afterwards. Each call to StGetNextEntryFast() must be paired with a matching call to StSubmitEntryFast(). When reading entries from the stream the caller must not invoke StSubmitEntryFast().; Simutrace reads and writes trace data in segments of fixed size (e.g., 64MiB). Whenever the handle reaches the end of a segment, Simutrace will proceed the handle to the next segment. This will include loading/submitting data from/to the server, causing a noticeable delay. Using appropriate access flags in the call to StStreamOpen() can significantly reduce latency and increase transfer rate for reads. See StreamAccessFlags for more information.; Use StWriteVariableData() and StReadVariableData() to work with variable-sized data types.; For optimal performance, the compiler should run with inlining permitted.; When writing to a stream, the buffer space returned by this method is not zeroed and may contain arbitrary data. Do not attempt to read or interpret the data. Instead, simply overwrite it.

Warning: Writing data to a stream with a read handle will lead to data loss.

Since: 3.0

See also: StGetNextEntry(); StStreamAppend(); StStreamOpen(); StSubmitEntry(); StWriteVariableData(); StReadVariableData()

SIMUTRACE_API void* StGetNextEntry ( StreamHandle * handlePtr )

This method performs the same operation as StGetNextEntryFast() as part of the client library exported interface. It is slower than StGetNextEntryFast() but does not require C function inlining.

Since: 3.1

See also: StGetNextEntryFast()

static void* StGetPreviousEntryFast ( StreamHandle * handlePtr )

inlinestatic

This method moves the read/write pointer of the supplied handle to the previous entry in the stream. The pointer returned by this method can only be used to read a single trace entry.

Parameters

handlePtr A pointer to the stream read handle. The method may allocate a new handle and update the supplied pointer. Calling the function with a handle to a dynamic stream is not supported.

Returns: A pointer to the previous trace entry if successful, NULL otherwise. For a more detailed error description call StGetLastError(). On error, the supplied handle will be invalidated. In contrast to a closed handle (see StStreamClose()), an invalidated handle is not freed and may be used to retry the operation. If successful, the caller must cast the pointer to the data type (e.g., DataWrite64) for the type supplied at stream registration.

Remarks: This method is not thread-safe when operating on the same handle.; The caller must not invoke StSubmitEntryFast().; Simutrace reads and writes trace data in segments of fixed size (e.g., 64MiB). Whenever the handle reaches the end of a segment, Simutrace will proceed the handle to the next segment. This will include loading/submitting data from/to the server, causing a noticeable delay. Using appropriate access flags in the call to StStreamOpen() can significantly reduce latency and increase transfer rate for reads. See StreamAccessFlags for more information.; Use StWriteVariableData() and StReadVariableData() to work with variable-sized data types. Reading variable-sized data backwards is not supported.; For optimal performance, the compiler should run with inlining permitted.

Warning: Writing data to a stream with a read handle will lead to data loss.

Since: 3.1

See also: StStreamOpen(); StReadVariableData()

SIMUTRACE_API void* StGetPreviousEntry ( StreamHandle * handlePtr )

This method performs the same operation as StGetPreviousEntryFast() as part of the client library exported interface. It is slower than StGetNextPreviousFast() but does not require C function inlining.

Since: 3.1

See also: StGetPreviousEntryFast()

static void StSubmitEntryFast ( StreamHandle handle )

inlinestatic

This method builds the closing operation when writing a new entry to a stream, signaling Simutrace that the entry has been fully written and is valid.

Parameters

handle The write handle of the stream, which has been used in the matching call to StGetNextEntryFast().

Remarks: When writing a new entry, call StSubmitEntryFast() afterwards. Each call to StGetNextEntryFast() must be paired with a matching call to StSubmitEntryFast(). When reading entries from the stream the caller must not invoke StSubmitEntryFast(). This is undefined behavior.

Since: 3.0

See also: StSubmitEntry(); StGetNextEntry()

SIMUTRACE_API void StSubmitEntry ( StreamHandle handle )

This method performs the same operation as StSubmitEntryFast() as part of the client library exported interface. It is slower than StSubmitEntryFast() but does not require C function inlining.

Since: 3.1

See also: StSubmitEntryFast()

SIMUTRACE_API size_t StWriteVariableData	(	StreamHandle *	handlePtr,
		byte *	sourceBuffer,
		size_t	sourceLength,
		uint64_t *	referenceOut
	)

In Simutrace, entries are required to be of fixed size. This method enables tracing of variable-sized data such as strings. To trace entries that contain variable-sized fields, the data fields should be replaced with fixed-size reference fields. The data itself can then be traced with this method.

Parameters

handlePtr	Pointer to a write handle for the stream that will receive the variable-sized data.
sourceBuffer	Pointer to a buffer containing the variable-sized data.
sourceLength	Length of the variable-sized data.
referenceOut	Pointer to a reference field receiving the reference to the variable-sized data in the given stream. This parameter may be NULL.

Returns: The number of bytes written, sourceLength if successful. For a more detailed error description call StGetLastError().

Remarks: The returned reference is only valid for the supplied stream. The caller thus have to remember the stream for which the reference is valid when reading the data.; The destination stream must be created with a variable entry size, see StStreamRegister() and makeVariableEntrySize().

Deprecated:: Before 3.1: The parameter referenceOut must not be NULL.

Since: 3.0

See also: makeVariableEntrySize(); StReadVariableData()

SIMUTRACE_API size_t StReadVariableData	(	StreamHandle *	handlePtr,
		uint64_t	reference,
		byte *	destinationBuffer
	)

This method reads variable-sized data from the supplied stream given a reference, originally returned by StWriteVariableData().

Parameters

handlePtr	Pointer to a read handle for the stream that stores the variable-sized data.
reference	Reference to the variable-sized data in the given stream.
destinationBuffer	Pointer to a buffer receiving the variable-sized data. The buffer needs to provide enough space. Supply `NULL` to determine the length of the data.

Returns: The length of the referenced variable-sized data in bytes, if successful, -1 otherwise. For a more detailed error description call StGetLastError().

Since: 3.0

See also: StWriteVariableData()

Variable Documentation

SIMUTRACE_API const uint32_t StClientVersion

Version number of the Simutrace client. This should ideally match the version of the server. The version number has the form: <Revision (16 bits), Major Version (8 bits), Minor Version (8 bits)> with the revision being stored in the high word.

Since: 3.0

See also: SIMUTRACE_VER_MAJOR; SIMUTRACE_VER_MINOR; SIMUTRACE_VER_REVISION

Functions

Variables

Function Documentation

Variable Documentation