OpenMPI  0.1.1
Master Control Interface

This interface is dedicated to managing master control files ( *.otf ) A master control file contains a mapping from process streams to processes and vice versa. More...

Files

file  OTF_MasterControl.h
 Provides access to process-stream-mapping, which are located in .otf files.
 

Typedefs

typedef struct struct_OTF_MapEntry OTF_MapEntry
 entry for 1:n mapping
 
typedef struct struct_OTF_Pair OTF_Pair
 entry for 1:1 mapping
 
typedef struct
struct_OTF_MasterControl 
OTF_MasterControl
 master control object. More...
 

Functions

OTF_MasterControlOTF_MasterControl_new (OTF_FileManager *manager)
 Creates an empty OTF_MasterControl object. More...
 
int OTF_MasterControl_read (OTF_MasterControl *mc, const char *namestub)
 INTERFACE CHANGED! Read a master control file according to namestub, reset the existing OTF_MasterControl structure and fill it according to the file. More...
 
void OTF_MasterControl_finish (OTF_MasterControl *mc)
 Destructor, delete OTF_MasterControl object. More...
 
void OTF_MasterControl_close (OTF_MasterControl *mc)
 Deletes a OTF_MasterControl object. More...
 
int OTF_MasterControl_append (OTF_MasterControl *mc, uint32_t argument, uint32_t value)
 Append the mapping argument -> value to the master control structure,. More...
 
int OTF_MasterControl_appendList (OTF_MasterControl *mc, uint32_t argument, uint32_t l, uint32_t *values)
 Append the mapping argument -> ( list of l values ) to the master control structure. More...
 
uint32_t OTF_MasterControl_mapReverse (OTF_MasterControl *mc, uint32_t value)
 Returns the argument to the given value. More...
 
int OTF_MasterControl_write (OTF_MasterControl *mc, const char *namestub)
 Writes a master control file with the current contents of the given object. More...
 
int OTF_MasterControl_check (OTF_MasterControl *mc)
 Checks if the current mapping is consistent in itself. More...
 
void OTF_MasterControl_print (OTF_MasterControl *mc)
 Prints the mapping to stderr. More...
 
OTF_MapEntryOTF_MasterControl_getEntry (OTF_MasterControl *mc, uint32_t argument)
 Returns the entry for the given argument. More...
 
OTF_MapEntryOTF_MasterControl_getEntryByIndex (OTF_MasterControl *mc, uint32_t index)
 Returns the entry for the given index. More...
 
OTF_PairOTF_MasterControl_getREntryByIndex (OTF_MasterControl *mc, uint32_t index)
 Returns a pair of value and argument for the given index. More...
 
uint32_t OTF_MasterControl_getCount (OTF_MasterControl *mc)
 Returns the number of arguments in the current list. More...
 
uint32_t OTF_MasterControl_getrCount (OTF_MasterControl *mc)
 Returns the number of arguments in current reverse list. More...
 
uint32_t OTF_MasterControl_getValueCount (OTF_MasterControl *mc, uint32_t argument)
 Returns the number of values for the given argument. More...
 
uint32_t * OTF_MasterControl_getValues (OTF_MasterControl *mc, uint32_t argument)
 Returns a pointer to the value array for 'argument'. More...
 
uint32_t OTF_MasterControl_getNewStreamId (OTF_MasterControl *mc)
 Returns a previously unused argument. More...
 

Detailed Description

This interface is dedicated to managing master control files ( *.otf ) A master control file contains a mapping from process streams to processes and vice versa.

A simple Example

This is example will create a simple mapping and read it again to show how reading and writing works with the master control file.

The need for creating your own master control file arises when you are not using the highlevel reader/writer, but the stream reader/writer.

#include <stdio.h>
#include <assert.h>
#include "otf.h"
int main( int argc, char** argv ) {
Declare a couple of variables.
uint32_t streamcount;
uint32_t a;
uint32_t i;
OTF_MapEntry* entry;
OTF_FileManager* manager;

Initialize the file manager and the mastercontrol.

manager= OTF_FileManager_open( 100 );
assert( manager );
mc = OTF_MasterControl_new( manager );

Add four processes (100,101,102,103) to two streams (1,2)

Write everything to the file "mytrace.otf" and close the master control.

Now initialize the master control structure and read the newly written master control file.

mc = OTF_MasterControl_new( manager );
OTF_MasterControl_read( mc, "mytrace" );

Visit all stream-process pairs and print them out

streamcount = OTF_MasterControl_getCount( mc );
for( i = 0; i < streamcount; ++i ) {
for( a = 0; a < entry->n; ++a ) {
printf( " stream %u contains process %u\n", entry->argument,
entry->values[a] );
}
}

Clean everything up before exiting the program

return 0;
}

Compile this using $ gcc -o test test.c otfconfig --libs.

The program will show this output:

*  stream 1 contains process 100
*  stream 1 contains process 101
*  stream 2 contains process 102
*  stream 2 contains process 103 

Typedef Documentation

master control object.

This object contains all information of the master control file.

Function Documentation

int OTF_MasterControl_append ( OTF_MasterControl mc,
uint32_t  argument,
uint32_t  value 
)

Append the mapping argument -> value to the master control structure,.

Parameters
mcPointer to an initialized OTF_Mastercontrol object. See also OTF_MasterControl_new().
argumentRepresents the stream identifier.
valueRepresents the process identifier.
Returns
1 on sucess, 0 if an error occurs (e.g. the new pair conflicts with the current mapping).

Referenced by OTF_MasterControl_appendList(), OTF_MasterControl_read(), and OTF_Writer_assignProcess().

int OTF_MasterControl_appendList ( OTF_MasterControl mc,
uint32_t  argument,
uint32_t  l,
uint32_t *  values 
)

Append the mapping argument -> ( list of l values ) to the master control structure.

This is equal to calling 'OTF_MasterControl_append()' with every value in list separately.

Parameters
mcPointer to an initialized OTF_Mastercontrol object. See also OTF_MasterControl_new().
argumentRepresents the stream identifier.
lNumber of elements in the value array.
valuesArray of process identifiers belonging to the stream.
Returns
1 on success, 0 if an error occurs (e.g. the new entries conflict with the current mapping).

References OTF_MasterControl_append().

int OTF_MasterControl_check ( OTF_MasterControl mc)

Checks if the current mapping is consistent in itself.

Parameters
mcPointer to an initialized OTF_Mastercontrol object. See also OTF_MasterControl_new().
Returns
1 on success, 0 if the mapping is not consistent in itself.

References struct_OTF_MapEntry::argument, struct_OTF_MasterControl::map, struct_OTF_MapEntry::n, struct_OTF_MasterControl::n, struct_OTF_MasterControl::rmap, struct_OTF_MasterControl::rn, and struct_OTF_MapEntry::values.

void OTF_MasterControl_close ( OTF_MasterControl mc)

Deletes a OTF_MasterControl object.

Parameters
mcPointer to an initialized OTF_Mastercontrol object. See also OTF_MasterControl_new().

Referenced by OTF_MasterControl_finish(), and OTF_Writer_setMasterControl().

void OTF_MasterControl_finish ( OTF_MasterControl mc)

Destructor, delete OTF_MasterControl object.

DEPRECATED

References OTF_MasterControl_close().

uint32_t OTF_MasterControl_getCount ( OTF_MasterControl mc)

Returns the number of arguments in the current list.

Parameters
mcPointer to an initialized OTF_Mastercontrol object. See also OTF_MasterControl_new().
Returns
Number of entrys in the current list. (equals the number of streams)

References struct_OTF_MasterControl::n.

Referenced by OTF_Writer_mapProcess().

OTF_MapEntry* OTF_MasterControl_getEntry ( OTF_MasterControl mc,
uint32_t  argument 
)

Returns the entry for the given argument.

Parameters
mcPointer to an initialized OTF_Mastercontrol object. See also OTF_MasterControl_new().
argumentRepresents the stream identifier.
Returns
The map entry belonging to the argument, or NULL if an error occurs.

References struct_OTF_MapEntry::argument, struct_OTF_MasterControl::map, and struct_OTF_MasterControl::n.

Referenced by OTF_MasterControl_getNewStreamId(), and OTF_MasterControl_getValueCount().

OTF_MapEntry* OTF_MasterControl_getEntryByIndex ( OTF_MasterControl mc,
uint32_t  index 
)

Returns the entry for the given index.

Parameters
mcPointer to an initialized OTF_Mastercontrol object. See also OTF_MasterControl_new().
indexIndex of the entry to return.
Returns
The map entry belonging to the index, or NULL if the index exceeds the mapping.

References struct_OTF_MasterControl::map.

Referenced by OTF_Reader_readDefinitions(), OTF_Reader_readMarkers(), and OTF_Writer_mapProcess().

uint32_t OTF_MasterControl_getNewStreamId ( OTF_MasterControl mc)

Returns a previously unused argument.

Of course, one cannot avoid collisions with arguments explicitly defined later on.

Parameters
mcPointer to an initialized OTF_Mastercontrol object. See also OTF_MasterControl_new().
Returns
Unused argument.

References struct_OTF_MapEntry::argument, struct_OTF_MasterControl::map, struct_OTF_MasterControl::n, and OTF_MasterControl_getEntry().

Referenced by OTF_Writer_mapProcess().

uint32_t OTF_MasterControl_getrCount ( OTF_MasterControl mc)

Returns the number of arguments in current reverse list.

Parameters
mcPointer to an initialized OTF_Mastercontrol object. See also OTF_MasterControl_new().
Returns
Number of entrys in the current reverse list. (equals the number of processes)

References struct_OTF_MasterControl::rn.

OTF_Pair* OTF_MasterControl_getREntryByIndex ( OTF_MasterControl mc,
uint32_t  index 
)

Returns a pair of value and argument for the given index.

Parameters
mcPointer to an initialized OTF_Mastercontrol object. See also OTF_MasterControl_new().
indexIndex of the pair in the reverse mapping.
Returns
Pair of value and argument belonging to the index, or NULL if the index exceeds the reverse mapping.

References struct_OTF_MasterControl::rmap.

uint32_t OTF_MasterControl_getValueCount ( OTF_MasterControl mc,
uint32_t  argument 
)

Returns the number of values for the given argument.

Parameters
mcPointer to an initialized OTF_Mastercontrol object. See also OTF_MasterControl_new().
argumentRepresents the stream identifier.
Returns
Number of values for the given argument, or 0 if the argument is unknown.

References struct_OTF_MapEntry::n, and OTF_MasterControl_getEntry().

uint32_t* OTF_MasterControl_getValues ( OTF_MasterControl mc,
uint32_t  argument 
)

Returns a pointer to the value array for 'argument'.

Get size of list with 'OTF_MasterControl_getValueCount()'.

Parameters
mcPointer to an initialized OTF_Mastercontrol object. See also OTF_MasterControl_new().
argumentRepresents the stream identifier.
Returns
Pointer to the value array for 'argument', or NULL if an error occurs.

References struct_OTF_MapEntry::argument, struct_OTF_MasterControl::map, struct_OTF_MasterControl::n, and struct_OTF_MapEntry::values.

uint32_t OTF_MasterControl_mapReverse ( OTF_MasterControl mc,
uint32_t  value 
)

Returns the argument to the given value.

If no mapping was defined make up a new one.

Parameters
mcPointer to an initialized OTF_Mastercontrol object. See also OTF_MasterControl_new().
valueRepresents the process identifier.
Returns
Argument to which the value belongs to.

References struct_OTF_MasterControl::rmap, and struct_OTF_MasterControl::rn.

Referenced by OTF_Writer_mapProcess().

OTF_MasterControl* OTF_MasterControl_new ( OTF_FileManager manager)

Creates an empty OTF_MasterControl object.

The returned object must be freed by OTF_MasterControl_close().

Parameters
managerFile handle manager.
Returns
newly created master control object

References struct_OTF_MasterControl::manager.

Referenced by OTF_Reader_open(), and OTF_Writer_open().

void OTF_MasterControl_print ( OTF_MasterControl mc)
int OTF_MasterControl_read ( OTF_MasterControl mc,
const char *  namestub 
)

INTERFACE CHANGED! Read a master control file according to namestub, reset the existing OTF_MasterControl structure and fill it according to the file.

Parameters
mcPointer to an initialized OTF_Mastercontrol object. See also OTF_MasterControl_new().
Returns
1 on success, 0 if an error occurs

References struct_OTF_MasterControl::manager, OTF_getFilename(), OTF_MasterControl_append(), OTF_RBuffer_close(), OTF_RBuffer_guaranteeRecord(), OTF_RBuffer_open(), OTF_RBuffer_readNewline(), OTF_RBuffer_readUint32(), OTF_RBuffer_setSize(), and OTF_RBuffer_testChar().

Referenced by OTF_Reader_open().

int OTF_MasterControl_write ( OTF_MasterControl mc,
const char *  namestub 
)

Writes a master control file with the current contents of the given object.

Parameters
mcPointer to an initialized OTF_Mastercontrol object. See also OTF_MasterControl_new().
namestubFile name prefix which.
Returns
1 on success, 0 if an error occurs.

References struct_OTF_MapEntry::argument, struct_OTF_MasterControl::manager, struct_OTF_MasterControl::map, struct_OTF_MapEntry::n, struct_OTF_MasterControl::n, OTF_getFilename(), OTF_WBuffer_close(), OTF_WBuffer_open(), OTF_WBuffer_setSize(), OTF_WBuffer_writeChar(), OTF_WBuffer_writeNewline(), OTF_WBuffer_writeUint32(), and struct_OTF_MapEntry::values.