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_trial_t
struct  cperfdmf_experiment_t
struct  cperfdmf_application_t
struct  cperfdmf_profile_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 (char *configFile)
void cperfdmf_finalize ()
int cperfdmf_connectDB (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 char *  configFile  ) 
 

initialize the cperfdmf system

Parameters:
configFile [in] location of perfdmf.cfg (e.g. /home/users/amorris/.ParaProf/perfdmf.cfg)
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 Fri Sep 2 11:27:17 2005 for C API for PerfDMF by  doxygen 1.3.9.1