Simutrace 3.2.2
Simulation Tracing Framework
SimuTrace.h File Reference

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 StreamTypeDescriptorStStreamFindMemoryType (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
informationOutA 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
typeThe type of the exception, which determines how to interpret the error code. Set this to EcUser for user-defined error codes.
codeOne of the pre-defined error codes or a user-defined one, depending on the exception type.
messageOptional 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
serverSpecifies 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
sessionThe 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
sessionThe 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
sessionThe id of the session to open a store in as originally returned by StSessionCreate().
specifierSimutrace 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.

alwaysCreateIndicates 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
sessionThe id of the session to open a store in as originally returned by StSessionCreate().
specifierSimutrace 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
sessionThe 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
sessionThe id of the session to be configured as originally returned by StSessionCreate().
configurationA 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
nameA friendly name of the new stream (e.g., "CPU Memory Accesses").
entrySizeThe size of a single trace entry in bytes. To specify a variable-sized entry type, use makeVariableEntrySize().
flagsSupplies the flags used for the type of the new stream.
descOutPointer 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
nameA friendly name of the new stream (e.g., "CPU Memory Accesses").
typePointer to a valid StreamTypeDescriptor structure, defining the desired type of the new stream.
descOutPointer 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
sizeArchitecture size of the simulated system.
accessTypeType of memory operations that the new stream should hold.
addressTypeThe semantic of the address field.
hasDataIndicates 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
nameA friendly name of the new stream (e.g., "Filtered memory accesses").
entrySizeThe size of a single trace entry in bytes. Variable-sized entries are not supported.
flagsSupplies the flags used for the type of the new stream.
userDataA 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.
operationsPointer to a set of operations that implement the logic of the dynamic stream.
descOutPointer 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
nameA friendly name of the new stream (e.g., "Filtered memory accesses").
typePointer to a valid StreamTypeDescriptor structure, defining the desired type of the new stream.
userDataA 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.
operationsPointer to a set of operations that implement the logic of the dynamic stream.
descOutPointer 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
sessionThe id of the session, whose store should register the stream.
descPointer 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
sessionThe id of the session, whose store should register the stream.
descPointer 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
sessionThe id of the session to enumerate all streams from.
bufferSizeTotal 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.
streamIdsOutSupplies 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
sessionThe id of the session that holds the stream of interest.
streamThe id of the stream to query.
informationOutA 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
sessionThe id of the session that holds the stream of interest. Must be INVALID_SESSION_ID, when supplying handle.
streamThe id of the stream to open a handle for. Must be INVALID_STREAM_ID, when supplying handle.
handleExisting 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
sessionThe id of the session that holds the stream of interest. Must be INVALID_SESSION_ID, when supplying handle.
streamThe id of the stream to open a handle for. Must be INVALID_STREAM_ID, when supplying handle.
typeType of property value that indicates which position in the stream should be opened. For further information on the possible query types see QueryIndexType.
valueA value used in the query specified by type. See QueryIndexType for more details.
flagsSupplies 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.
handleAn 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
handleThe 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
handlePtrA 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
handlePtrA 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
handleThe 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
handlePtrPointer to a write handle for the stream that will receive the variable-sized data.
sourceBufferPointer to a buffer containing the variable-sized data.
sourceLengthLength of the variable-sized data.
referenceOutPointer 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
handlePtrPointer to a read handle for the stream that stores the variable-sized data.
referenceReference to the variable-sized data in the given stream.
destinationBufferPointer 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
Karlsruhe Institute of Technology (KIT)
Operating Systems Group

http://simutrace.org
Generated by doxygen 1.8.10
Marc Rittinghaus