trace.h File Reference


Detailed Description

Implements a database for keeping track of kernel calls.

#include <oski/common.h>
#include <oski/simplelist.h>

Go to the source code of this file.

Data Structures

struct  oski_tracerec_t
 A trace record that stores the number of times a kernel has been (and/or will be) called with a particular argument list. More...

Defines

#define INC_OSKI_TRACE_H
 oski/trace.h included.
#define INVALID_TRACEREC   ((oski_tracerec_t *)NULL)
 NULL trace record.
#define INVALID_TRACE   ((oski_trace_t)NULL)
 NULL trace.
#define TIME_NOT_AVAIL   ((double)(-1.0))
 Time not available.
#define oski_RecordCall(trace, id, args, args_size, func, time_elapsed)   oski_RecordCalls(trace, id, args, args_size, func, 1, time_elapsed)
 Wrapper around oski_RecordCalls assuming just 1 call.

Typedefs

typedef int(* oski_traceargscmp_funcpt )(const void *a, const void *b)
 Type for a function to compare two trace arguments of the same type.
typedef simplelist_toski_trace_t
 A trace is a list of kernel calls and their argument signatures.

Functions

oski_trace_t oski_CreateTrace (void)
 Create and return a new trace.
void oski_DestroyTrace (oski_trace_t trace)
 Destroy a trace.
int oski_RecordCalls (oski_trace_t trace, oski_id_t kernel_id, const void *args, size_t args_bytes, oski_traceargscmp_funcpt func_compare, size_t num_new_calls, double time_elapsed)
 Save a kernel call to a trace.
size_t oski_GetNumCalls (const oski_trace_t trace, oski_id_t kernel_id, const void *args, size_t args_bytes, oski_traceargscmp_funcpt func_compare)
 Returns the frequency of a particular kernel call for all matching records.
int oski_MatchesTraceRecord (const oski_tracerec_t *rec, oski_id_t kernel_id, const void *args, size_t args_bytes, oski_traceargscmp_funcpt func_compare)
 Returns 1 if a given trace record matches a query request, or 0 otherwise.


Typedef Documentation

typedef int(* oski_traceargscmp_funcpt)(const void *a, const void *b)
 

Type for a function to compare two trace arguments of the same type.

This type is a pointer to a comparison function f(a, b) where a and b are pointers to kernel-specific argument lists (i.e., the 'args' field of a oski_tracerec_t structure).

When an object of this type is passed to one of the routines below, then the first argument `a' is ALWAYS the trace argument list for the record stored in the trace, and second argument `b' is the trace argument list being sought.


Function Documentation

size_t oski_GetNumCalls const oski_trace_t  trace,
oski_id_t  kernel_id,
const void *  args,
size_t  args_bytes,
oski_traceargscmp_funcpt  func_compare
 

Returns the frequency of a particular kernel call for all matching records.

Parameters:
[in] trace Trace to search.
[in] kernel_id ID# of the kernel to find.
[in] args Kernel-specific argument list. If set to NULL, then match any record with kernel ID# kernel_id.
[in] args_bytes Size of object pointed to by 'args' in bytes.
[in] func_compare Function to perform record-matching comparison. If NULL, then do a byte-wise comparison.
Returns:
The total number of calls across all records that match according to the comparison function, func_compare.

int oski_MatchesTraceRecord const oski_tracerec_t rec,
oski_id_t  kernel_id,
const void *  args,
size_t  args_bytes,
oski_traceargscmp_funcpt  func_compare
 

Returns 1 if a given trace record matches a query request, or 0 otherwise.

Parameters:
[in] rec Trace record to test.
[in] kernel_id Kernel to match, or INVALID_ID to match any kernel.
[in] args Arguments of the given kernel. (Ignored if kernel_id == INVALID_ID.)
[in] args_bytes Size of 'args' in bytes. (Ignored if kernel_id == INVALID_ID.)
[in] func_compare A pointer to a user-defined function $f(a, b)$ to compare two kernel-specific argument lists, $a$ and $b$. If func_compare == NULL, then byte-wise comparisons are used by default. (Ignored if kernel_id == INVALID_ID.)
Returns:
1 if 'rec' matches the query request, ('kernel_id', 'args', 'args_bytes', 'func_compare'), or 0 otherwise. If 'rec' == INVALID_TRACREC, this routine returns 0.

int oski_RecordCalls oski_trace_t  trace,
oski_id_t  kernel_id,
const void *  args,
size_t  args_bytes,
oski_traceargscmp_funcpt  func_compare,
size_t  num_new_calls,
double  time_elapsed
 

Save a kernel call to a trace.

Parameters:
[in,out] trace Trace to search and update.
[in] kernel_id ID# of the kernel.
[in] args Kernel-specific argument list. If set to NULL, then the caller requests that the update occur to the first record matching just kernel_id.
[in] args_bytes Size of the data pointed to by args, in bytes.
[in] func_compare Function to perform record-matching comparison. If set to NULL, then a default function that performs bit-wise equality comparison is used.
[in] num_new_calls Number of calls to record.
[in] time_elapsed Number of seconds of execution time due to these calls, or TIME_NOT_AVAIL.
This routine searches for the first record (one with lowest ID#) in the trace that "matches" the given kernel. A match means that the following two conditions hold:
  1. func_compare(record->args, args) == 0 OR record->args == NULL OR args == NULL.
  2. (time_elapsed < 0) == (record->time_elapsed < 0)

If a matching record cannot be found, then a new one is created.

Returns:
0 on success. If trace of kernel_id are invalid, returns an error code (ERR_BAD_ARG) and takes no action. If there is not enough memory to create a new trace record, returns ERR_OUT_OF_MEMORY.


Generated on Wed Sep 19 16:41:23 2007 for BeBOP Optimized Sparse Kernel Interface Library by  doxygen 1.4.6