Main Page   Modules   Data Structures   File List   Data Fields   Globals  

cperfdmf.h File Reference

Go to the source code of this file.

Data Structures

struct  cperfdmf_application_t
struct  cperfdmf_experiment_t
struct  cperfdmf_profile_t
struct  cperfdmf_trial_t
struct  cperfdmf_userEvent_t

Typedefs

typedef cperfdmf_trial_t cperfdmf_trial_t
typedef cperfdmf_experiment_t cperfdmf_experiment_t
typedef cperfdmf_application_t cperfdmf_application_t
typedef cperfdmf_profile_t cperfdmf_profile_t
typedef cperfdmf_userEvent_t cperfdmf_userEvent_t

Enumerations

enum  cperfdmf_error_t {
  CPERFDMF_OK = 0, CPERFDMF_ERR = -1, CPERFDMF_NON_EXISTENT = -2, CPERFDMF_ERR_NO_PROFILES = -3,
  CPERFDMF_ERR_INTERNAL_ERROR = -6, CPERFDMF_ERR_DB_NOT_INITIALIZED = -7, CPERFDMF_ERR_SESSION_NOT_INITIALIZED = -8, CPERFDMF_ERR_JAVA_EXCEPTION = -9
}

Functions

int cperfdmf_initialize ()
void cperfdmf_finalize ()
int cperfdmf_connectDB (char *configFile, char *password)
int cperfdmf_getApplications (cperfdmf_application_t **applications, int *numApplications)
int cperfdmf_getExperiments (cperfdmf_experiment_t **experiments, int *numExperiments, int applicationId)
int cperfdmf_getTrials (cperfdmf_trial_t **trials, int *numTrials, int experimentId)
int cperfdmf_loadTrial (int trialId)
int cperfdmf_saveApplication (cperfdmf_application_t *application)
int cperfdmf_saveExperiment (cperfdmf_experiment_t *experiment)
int cperfdmf_saveTrial (cperfdmf_trial_t *trial)
int cperfdmf_uploadTauOutput (int *trialId, char *path, int experimentId)
int cperfdmf_deleteApplication (int applicationId)
int cperfdmf_deleteExperiment (int experimentId)
int cperfdmf_deleteTrial (int trialId)
void cperfdmf_freeApplicationList (cperfdmf_application_t *applications, int numApplications)
void cperfdmf_freeExperimentList (cperfdmf_experiment_t *experiments, int numExperiments)
void cperfdmf_freeTrialList (cperfdmf_trial_t *trials, int numTrials)
int cperfdmf_loadTauOutput (char *path)
int cperfdmf_getMetrics (char ***metrics, int *numMetrics)
int cperfdmf_getFunctions (char ***functions, int *numFunctions)
int cperfdmf_getNumNodes (int *numNodes)
int cperfdmf_getNumContexts (int *numContexts, int node)
int cperfdmf_getNumThreads (int *numThreads, int node, int context)
int cperfdmf_getMeanValues (cperfdmf_profile_t *prof, int functionId, int metric)
int cperfdmf_getTotalValues (cperfdmf_profile_t *prof, int functionId, int metric)
int cperfdmf_getValues (cperfdmf_profile_t *prof, int functionId, int metric, int node, int context, int thread)
int cperfdmf_queryNodeExists (int *exists, int node)
int cperfdmf_queryContextExists (int *exists, int node, int context)
int cperfdmf_queryThreadExists (int *exists, int node, int context, int thread)
int cperfdmf_getGroups (char ***groups, int *numGroups)
int cperfdmf_getUserEvents (cperfdmf_userEvent_t **userEvents, int *numUserEvents, int node, int context, int thread)
char * cperfdmf_getExtendedError (void)
char * cperfdmf_errToString (int code)


Detailed Description

The CPERFDMF (C api to PerfdMf) API

Author:
Alan Morris
Using the C api to PerfDMF:

See also:
testApp.c

Typedef Documentation

typedef struct cperfdmf_application_t cperfdmf_application_t
 

Holds all metadeta concerning a single application from the database

typedef struct cperfdmf_experiment_t cperfdmf_experiment_t
 

Holds all metadeta concerning a single experiment from the database

typedef struct cperfdmf_profile_t cperfdmf_profile_t
 

Holds the actual values for a timer (function)

typedef struct cperfdmf_trial_t cperfdmf_trial_t
 

Holds all metadata regarding a single trial from the database

typedef struct cperfdmf_userEvent_t cperfdmf_userEvent_t
 

Holds the data for TAU user events


Function Documentation

char * cperfdmf_errToString int    code
 

Returns a string equivalent of the given code

Parameters:
code  [in] int, the code
Returns:
c-string, the string equivalent of 'code'

void cperfdmf_finalize  
 

finalize the cperfdmf system

char * cperfdmf_getExtendedError void   
 

Get extended error information. Use this function to get extended error information when a function has returned the CPERFDMF_ERR_INTERNAL_ERROR value

Returns:
char* : c-string containing the extended error string, do not free().

int cperfdmf_getFunctions char ***    functions,
int *    numFunctions
 

Get the list of functions for the current session

Parameters:
functions  [out] pointer to an array of c-style strings. The array will be allocated and generated by the API. The user may free it at any time.
numFunctions  [out] pointer to an integer. The value will contain the number of functions (the size of the functions array)
Return values:
CPERFDMF_OK  ok
CPERFDMF_ERR_SESSION_NOT_INITIALIZED  session is not initialized
CPERFDMF_ERR_INTERNAL_ERROR  use getExtendedError() for details

int cperfdmf_getGroups char ***    groups,
int *    numGroups
 

Retrieve the group names

Parameters:
groups  [out] pointer to array of c-style strings. The array will be allocated and generated by the API. The user may free it at any time.
numGroups  [out] pointer to an integer. The value will contain the number of groups (the size of the groups array)
Return values:
CPERFDMF_OK  ok
CPERFDMF_ERR_SESSION_NOT_INITIALIZED  session is not initialized
CPERFDMF_ERR_INTERNAL_ERROR  use getExtendedError() for details

int cperfdmf_getMeanValues cperfdmf_profile_t   prof,
int    functionId,
int    metric
 

Get mean profile values for the current session

Parameters:
prof  [out] pointer to a cperfdmf_profile_t. prof will contain the profile retrieved.
functionId  [in] which profile should be retrieved. The ascii name for a given index can be found by indexing into the array from cperfdmf_getFunctions.
metric  [in] which metric to retrieve (likewise indexed from cperfdmf_getMetrics
Return values:
CPERFDMF_OK  ok
CPERFDMF_NON_EXISTENT  No mean values were found (this probably indicates something is wrong with the data)
CPERFDMF_ERR_SESSION_NOT_INITIALIZED  session is not initialized
CPERFDMF_ERR_INTERNAL_ERROR  use getExtendedError() for details

int cperfdmf_getMetrics char ***    metrics,
int *    numMetrics
 

Get the metrics for the current session

Parameters:
metrics  [out] pointer to an array of c-strings. The array will be allocated and generated by the API. The user may free it at any time.
numMetrics  [out] pointer to an integer. The value will contain the number of metrics (the size of the metrics array)
Return values:
CPERFDMF_OK  ok
CPERFDMF_ERR_SESSION_NOT_INITIALIZED  session is not initialized
CPERFDMF_ERR_INTERNAL_ERROR  use getExtendedError() for details

int cperfdmf_getNumContexts int *    numContexts,
int    node
 

Get the number of contexts for the given node in the current session

Parameters:
numContexts  [out] pointer to an integer. The value will contain the number of contexts for the given node
node  [in] integer, the node to query
Return values:
CPERFDMF_OK  ok
CPERFDMF_ERR_SESSION_NOT_INITIALIZED  session is not initialized
CPERFDMF_ERR_INTERNAL_ERROR  use getExtendedError() for details

int cperfdmf_getNumNodes int *    numNodes
 

Get the number of nodes for the current session

Parameters:
numNodes  [out] pointer to an integer. The value will contain the number of nodes for the current session
Return values:
CPERFDMF_OK  ok
CPERFDMF_ERR_SESSION_NOT_INITIALIZED  session is not initialized
CPERFDMF_ERR_INTERNAL_ERROR  use getExtendedError() for details

int cperfdmf_getNumThreads int *    numThreads,
int    node,
int    context
 

Get the number of threads for the given node and context in the current session

Parameters:
numThreads  [out] pointer to an integer. The value will contain the number of threads for the given node and context
node  [in] integer, the node to query
context  [in] integer, the context to query
Return values:
CPERFDMF_OK  ok
CPERFDMF_ERR_SESSION_NOT_INITIALIZED  session is not initialized
CPERFDMF_ERR_INTERNAL_ERROR  use getExtendedError() for details

int cperfdmf_getTotalValues cperfdmf_profile_t   prof,
int    functionId,
int    metric
 

Get total profile values for the current session

Parameters:
prof  [out] pointer to a cperfdmf_profile_t. prof will contain the profile retrieved.
functionId  [in] which profile should be retrieved. The ascii name for a given index can be found by indexing into the array from cperfdmf_getFunctions.
metric  [in] which metric to retrieve (likewise indexed from cperfdmf_getMetrics
Return values:
CPERFDMF_OK  ok
CPERFDMF_NON_EXISTENT  No total values were found (this probably indicates something is wrong with the data)
CPERFDMF_ERR_SESSION_NOT_INITIALIZED  session is not initialized
CPERFDMF_ERR_INTERNAL_ERROR  use getExtendedError() for details

int cperfdmf_getUserEvents cperfdmf_userEvent_t **    userEvents,
int *    numUserEvents,
int    node,
int    context,
int    thread
 

Retrieve the user events for the current session

Parameters:
userEvents  [out]
numUserEvents  [out]
node  [in]
context  [in]
thread  [in]
Return values:
CPERFDMF_OK  ok
CPERFDMF_ERR_SESSION_NOT_INITIALIZED  session is not initialized
CPERFDMF_NON_EXISTENT  No user events were found for the requested node:context:thread
CPERFDMF_ERR_INTERNAL_ERROR  use getExtendedError() for details

int cperfdmf_getValues cperfdmf_profile_t   prof,
int    functionId,
int    metric,
int    node,
int    context,
int    thread
 

Get profile values for the current session

Parameters:
prof  [out] pointer to a cperfdmf_profile_t. prof will contain the profile retrieved.
functionId  [in] which profile should be retrieved. The ascii name for a given index can be found by indexing into the array from cperfdmf_getFunctions.
metric  [in] which metric to retrieve (likewise indexed from cperfdmf_getMetrics
node  [in] which node to retrieve
context  [in] which context to retrieve
thread  [in] which thread to retrieve
Return values:
CPERFDMF_OK  ok
CPERFDMF_NON_EXISTENT  the given node:context:thread did not have a value for this function:metric (this is often expected in the case that a given thread does not call all instrumented functions)
CPERFDMF_ERR_SESSION_NOT_INITIALIZED  session is not initialized
CPERFDMF_ERR_INTERNAL_ERROR  use getExtendedError() for details

int cperfdmf_initialize  
 

initialize the cperfdmf system

Return values:
CPERFDMF_OK  ok
CPERFDMF_ERR  failure

int cperfdmf_loadTauOutput char *    path
 

Load raw TAU output files (profile.*)

Parameters:
path  [in] directory containing profile files
Return values:
CPERFDMF_OK  ok
CPERFDMF_ERR_NO_PROFILES  could not find profile.* files in the given path
CPERFDMF_ERR_INTERNAL_ERROR  use getExtendedError() for details

int cperfdmf_queryContextExists int *    exists,
int    node,
int    context
 

Query if a given context exists in the trial/profiles

Parameters:
exists  [out] 0 if the context does not exist, 1 if it does
node  [in] integer, which node to query.
context  [in] integer, which context to query.
Return values:
CPERFDMF_OK  ok
CPERFDMF_ERR_SESSION_NOT_INITIALIZED  session is not initialized
CPERFDMF_ERR_INTERNAL_ERROR  use getExtendedError() for details

int cperfdmf_queryNodeExists int *    exists,
int    node
 

Query if a given node exists in the trial/profiles

Parameters:
exists  [out] 0 if the node does not exist, 1 if it does
node  [in] integer, which node to query.
Return values:
CPERFDMF_OK  ok
CPERFDMF_ERR_SESSION_NOT_INITIALIZED  session is not initialized
CPERFDMF_ERR_INTERNAL_ERROR  use getExtendedError() for details

int cperfdmf_queryThreadExists int *    exists,
int    node,
int    context,
int    thread
 

Query if a given context exists in the trial/profiles

Parameters:
exists  [out] 0 if the thread does not exist, 1 if it does
node  [in] integer, which node to query.
context  [in] integer, which context to query.
thread  [in] integer, which thread to query.
Return values:
CPERFDMF_OK  ok
CPERFDMF_ERR_SESSION_NOT_INITIALIZED  session is not initialized
CPERFDMF_ERR_INTERNAL_ERROR  use getExtendedError() for details


Generated on Thu Aug 19 14:21:54 2004 for C API for PerfDMF by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002