2.3-trunk (revision 4758)
OTF2_Archive.h
Go to the documentation of this file.
1 /*
2  * This file is part of the Score-P software (http://www.score-p.org)
3  *
4  * Copyright (c) 2009-2013,
5  * RWTH Aachen University, Germany
6  *
7  * Copyright (c) 2009-2013,
8  * Gesellschaft fuer numerische Simulation mbH Braunschweig, Germany
9  *
10  * Copyright (c) 2009-2014,
11  * Technische Universitaet Dresden, Germany
12  *
13  * Copyright (c) 2009-2013,
14  * University of Oregon, Eugene, USA
15  *
16  * Copyright (c) 2009-2013,
17  * Forschungszentrum Juelich GmbH, Germany
18  *
19  * Copyright (c) 2009-2013,
20  * German Research School for Simulation Sciences GmbH, Juelich/Aachen, Germany
21  *
22  * Copyright (c) 2009-2013,
23  * Technische Universitaet Muenchen, Germany
24  *
25  * This software may be modified and distributed under the terms of
26  * a BSD-style license. See the COPYING file in the package base
27  * directory for details.
28  *
29  */
30 
31 
32 #ifndef OTF2_ARCHIVE_H
33 #define OTF2_ARCHIVE_H
34 
35 
162 #include <stdint.h>
163 
164 
165 #include <otf2/OTF2_ErrorCodes.h>
166 
167 
168 #include <otf2/OTF2_Callbacks.h>
169 #include <otf2/OTF2_DefWriter.h>
170 #include <otf2/OTF2_DefReader.h>
171 #include <otf2/OTF2_EvtWriter.h>
172 #include <otf2/OTF2_EvtReader.h>
173 #include <otf2/OTF2_SnapWriter.h>
174 #include <otf2/OTF2_SnapReader.h>
179 #include <otf2/OTF2_Thumbnail.h>
180 #include <otf2/OTF2_MarkerWriter.h>
181 #include <otf2/OTF2_MarkerReader.h>
182 
183 
184 #ifdef __cplusplus
185 extern "C" {
186 #endif /* __cplusplus */
187 
188 
194 #define OTF2_CHUNK_SIZE_EVENTS_DEFAULT ( 1024 * 1024 )
195 
196 
202 #define OTF2_CHUNK_SIZE_DEFINITIONS_DEFAULT ( 4 * 1024 * 1024 )
203 
204 
210 typedef struct OTF2_Archive_struct OTF2_Archive;
211 
212 
272 OTF2_Archive_Open( const char* archivePath,
273  const char* archiveName,
274  const OTF2_FileMode fileMode,
275  const uint64_t chunkSizeEvents,
276  const uint64_t chunkSizeDefs,
277  const OTF2_FileSubstrate fileSubstrate,
278  const OTF2_Compression compression );
279 
280 
292 OTF2_Archive_Close( OTF2_Archive* archive );
293 
309 OTF2_Archive_Flush( OTF2_Archive* archive );
310 
327  OTF2_FileMode newFileMode );
328 
329 
348  uint64_t chunkSize );
349 
350 
364  const char* machineName );
365 
366 
380  const char* description );
381 
382 
396  const char* creator );
397 
398 
410  const OTF2_FlushCallbacks* flushCallbacks,
411  void* flushData );
412 
413 
425  const OTF2_MemoryCallbacks* memoryCallbacks,
426  void* memoryData );
427 
428 
444  const OTF2_CollectiveCallbacks* collectiveCallbacks,
445  void* collectiveData,
446  OTF2_CollectiveContext* globalCommContext,
447  OTF2_CollectiveContext* localCommContext );
448 
449 
459 
460 
471  bool* result );
472 
473 
495  const OTF2_LockingCallbacks* lockingCallbacks,
496  void* lockingData );
497 
498 
526  OTF2_Hint hint,
527  void* value );
528 
529 
556  const char* name,
557  const char* value,
558  bool overwrite );
559 
560 
584  const char* name,
585  bool value,
586  bool overwrite );
587 
588 
601  uint32_t* numberOfProperties,
602  char*** names );
603 
604 
620  const char* name,
621  char** value );
622 
623 
636  uint64_t* id );
637 
638 
648  uint64_t* numberOfLocations );
649 
650 
660  uint64_t* numberOfDefinitions );
661 
662 
672  char** machineName );
673 
674 
684  char** description );
685 
686 
696  char** creator );
697 
698 
710  uint8_t* major,
711  uint8_t* minor,
712  uint8_t* bugfix );
713 
714 
725  uint64_t* chunkSizeEvents,
726  uint64_t* chunkSizeDefs );
727 
728 
738  OTF2_FileSubstrate* substrate );
739 
740 
750  OTF2_Compression* compression );
751 
752 
763  OTF2_LocationRef location );
764 
765 
776  OTF2_LocationRef location );
777 
778 
790 
791 
804  OTF2_LocationRef location );
805 
806 
826  const char* name,
827  const char* description,
828  OTF2_ThumbnailType type,
829  uint32_t numberOfSamples,
830  uint32_t numberOfMetrics,
831  const uint64_t* refsToDefs );
832 
833 
845 
846 
857  OTF2_LocationRef location );
858 
859 
869 
870 
881  OTF2_LocationRef location );
882 
883 
893 
894 
907  OTF2_LocationRef location );
908 
909 
921 
922 
935  uint32_t number );
936 
937 
949 
950 
960  OTF2_EvtWriter* writer );
961 
962 
972  OTF2_DefWriter* writer );
973 
974 
986  OTF2_MarkerWriter* writer );
987 
988 
1000  OTF2_SnapWriter* writer );
1001 
1002 
1020  OTF2_GlobalDefWriter* writer );
1021 
1022 
1032  OTF2_EvtReader* reader );
1033 
1034 
1046  OTF2_ThumbReader* reader );
1047 
1048 
1060  OTF2_GlobalEvtReader* globalEvtReader );
1061 
1062 
1072  OTF2_DefReader* reader );
1073 
1074 
1084  OTF2_GlobalDefReader* globalDefReader );
1085 
1086 
1098  OTF2_SnapReader* reader );
1099 
1100 
1113  OTF2_GlobalSnapReader* globalSnapReader );
1114 
1115 
1127  OTF2_MarkerReader* markerReader );
1128 
1129 
1142  uint32_t* number );
1143 
1144 
1157  uint32_t number );
1158 
1159 
1172  uint32_t* number );
1173 
1174 
1188 
1189 
1203 
1204 
1218 
1219 
1233 
1234 
1248 
1249 
1263 
1264 
1277  OTF2_LocationRef location );
1278 
1279 
1280 #ifdef __cplusplus
1281 }
1282 #endif /* __cplusplus */
1283 
1284 
1285 #endif /* !OTF2_ARCHIVE_H */
OTF2_ErrorCode OTF2_Archive_OpenSnapFiles(OTF2_Archive *archive)
Open the snapshots file container.
OTF2_ErrorCode OTF2_Archive_CloseEvtFiles(OTF2_Archive *archive)
Closes the events file container.
struct OTF2_MarkerReader_struct OTF2_MarkerReader
OTF2 marker reader handle.
Definition: OTF2_GeneralDefinitions.h:268
OTF2_ErrorCode OTF2_Archive_GetCompression(OTF2_Archive *archive, OTF2_Compression *compression)
Get compression mode (none or zlib)
struct OTF2_GlobalDefReader_struct OTF2_GlobalDefReader
OTF2 global definition reader handle.
Definition: OTF2_GeneralDefinitions.h:256
OTF2_ErrorCode OTF2_Archive_IsMaster(OTF2_Archive *archive, bool *result)
Determines if this archive is the master object which handles the global archive state (anchor file...
OTF2_ErrorCode OTF2_Archive_SetLockingCallbacks(OTF2_Archive *archive, const OTF2_LockingCallbacks *lockingCallbacks, void *lockingData)
Set the locking callbacks for the archive.
OTF2_ErrorCode OTF2_Archive_SetSerialCollectiveCallbacks(OTF2_Archive *archive)
Convenient function to set the collective callbacks to an serial implementation.
uint64_t OTF2_LocationRef
Type used to indicate a reference to a Location definition.
Definition: OTF2_GeneralDefinitions.h:139
This is the local definition reader, which reads location dependent definitions, and can also be used...
OTF2_ErrorCode OTF2_Archive_CloseThumbReader(OTF2_Archive *archive, OTF2_ThumbReader *reader)
Close an opened thumbnail reader.
OTF2_ErrorCode OTF2_Archive_SetDefChunkSize(OTF2_Archive *archive, uint64_t chunkSize)
Set the definition chunksize.
OTF2_ErrorCode OTF2_Archive_CloseGlobalSnapReader(OTF2_Archive *archive, OTF2_GlobalSnapReader *globalSnapReader)
Close the opened global snapshot reader.
OTF2_GlobalEvtReader * OTF2_Archive_GetGlobalEvtReader(OTF2_Archive *archive)
Get a global event reader.
OTF2_ErrorCode OTF2_Archive_SwitchFileMode(OTF2_Archive *archive, OTF2_FileMode newFileMode)
Switch file mode of the archive.
OTF2_ErrorCode OTF2_Archive_CloseMarkerWriter(OTF2_Archive *archive, OTF2_MarkerWriter *writer)
Close an opened marker writer.
OTF2_ThumbReader * OTF2_Archive_GetThumbReader(OTF2_Archive *archive, uint32_t number)
Get a thumb reader.
OTF2_ErrorCode OTF2_Archive_CloseDefFiles(OTF2_Archive *archive)
Closes the local definitions file container.
OTF2_EvtWriter * OTF2_Archive_GetEvtWriter(OTF2_Archive *archive, OTF2_LocationRef location)
Get a local event writer.
OTF2_ErrorCode OTF2_Archive_Close(OTF2_Archive *archive)
Close an opened archive.
uint8_t OTF2_Hint
Wrapper for enum OTF2_Hint_enum.
Definition: OTF2_GeneralDefinitions.h:381
OTF2_ErrorCode OTF2_Archive_GetVersion(OTF2_Archive *archive, uint8_t *major, uint8_t *minor, uint8_t *bugfix)
Get format version.
This is the definition reader.
OTF2_SnapWriter * OTF2_Archive_GetSnapWriter(OTF2_Archive *archive, OTF2_LocationRef location)
Get a local snap writer.
OTF2_ErrorCode OTF2_Archive_CloseGlobalEvtReader(OTF2_Archive *archive, OTF2_GlobalEvtReader *globalEvtReader)
Closes the global event reader.
OTF2_ErrorCode OTF2_Archive_GetTraceId(OTF2_Archive *archive, uint64_t *id)
Get the identifier of the trace file.
Struct which holds all collective callbacks.
Definition: OTF2_Callbacks.h:490
struct OTF2_ThumbReader_struct OTF2_ThumbReader
Keeps all necessary information about the event reader. See OTF2_ThumbReader_struct for detailed info...
Definition: OTF2_Thumbnail.h:43
This file provides all routines that read marker records.
This layer always writes globally defined OTF2 definition records and is used to write either the glo...
This file provides all routines that write definition records of a single location.
OTF2_MarkerWriter * OTF2_Archive_GetMarkerWriter(OTF2_Archive *archive)
Get a marker writer.
OTF2_ErrorCode
Definition: OTF2_ErrorCodes.h:54
OTF2_ErrorCode OTF2_Archive_GetFileSubstrate(OTF2_Archive *archive, OTF2_FileSubstrate *substrate)
Get the file substrate (posix, sion, none)
Structure holding the flush callbacks.
Definition: OTF2_Callbacks.h:145
OTF2_ErrorCode OTF2_Archive_Flush(OTF2_Archive *archive)
Flushes all buffers associated with an archive.
OTF2_ErrorCode OTF2_Archive_GetProperty(OTF2_Archive *archive, const char *name, char **value)
Get the value of the named trace file property.
OTF2_ErrorCode OTF2_Archive_CloseSnapFiles(OTF2_Archive *archive)
Closes the snapshots file container.
This lowest user-visible layer provides write routines to read and write thumbnail data...
OTF2_ErrorCode OTF2_Archive_CloseGlobalDefReader(OTF2_Archive *archive, OTF2_GlobalDefReader *globalDefReader)
Closes the global definition reader.
OTF2_ErrorCode OTF2_Archive_OpenDefFiles(OTF2_Archive *archive)
Open the local definitions file container.
struct OTF2_DefWriter_struct OTF2_DefWriter
Handle definition for the external definition writer.
Definition: OTF2_DefWriter.h:63
OTF2_GlobalDefWriter * OTF2_Archive_GetGlobalDefWriter(OTF2_Archive *archive)
Get a global definition writer.
OTF2_GlobalSnapReader * OTF2_Archive_GetGlobalSnapReader(OTF2_Archive *archive)
Get a global snap reader.
uint8_t OTF2_ThumbnailType
Wrapper for enum OTF2_ThumbnailType_enum.
Definition: OTF2_GeneralDefinitions.h:927
OTF2_ErrorCode OTF2_Archive_GetDescription(OTF2_Archive *archive, char **description)
Get description.
OTF2_ErrorCode OTF2_Archive_SetMemoryCallbacks(OTF2_Archive *archive, const OTF2_MemoryCallbacks *memoryCallbacks, void *memoryData)
Set the memory callbacks for the archive.
OTF2_ErrorCode OTF2_Archive_GetNumberOfThumbnails(OTF2_Archive *archive, uint32_t *number)
Get the number of thumbnails.
OTF2_ErrorCode OTF2_Archive_SetDescription(OTF2_Archive *archive, const char *description)
Set a description.
OTF2_ErrorCode OTF2_Archive_GetChunkSize(OTF2_Archive *archive, uint64_t *chunkSizeEvents, uint64_t *chunkSizeDefs)
Get the chunksize.
struct OTF2_MarkerWriter_struct OTF2_MarkerWriter
Handle definition for the external marker writer.
Definition: OTF2_MarkerWriter.h:42
OTF2_EvtReader * OTF2_Archive_GetEvtReader(OTF2_Archive *archive, OTF2_LocationRef location)
Get a local event reader.
OTF2_MarkerReader * OTF2_Archive_GetMarkerReader(OTF2_Archive *archive)
Get a marker reader.
OTF2_ErrorCode OTF2_Archive_CloseGlobalDefWriter(OTF2_Archive *archive, OTF2_GlobalDefWriter *writer)
Close an opened global definition writer.
OTF2_ErrorCode OTF2_Archive_SetFlushCallbacks(OTF2_Archive *archive, const OTF2_FlushCallbacks *flushCallbacks, void *flushData)
Set the flush callbacks for the archive.
struct OTF2_SnapReader_struct OTF2_SnapReader
OTF2 local snap reader handle.
Definition: OTF2_GeneralDefinitions.h:260
OTF2_ErrorCode OTF2_Archive_SetBoolProperty(OTF2_Archive *archive, const char *name, bool value, bool overwrite)
Add or remove a boolean trace file property to this archive.
OTF2_ErrorCode OTF2_Archive_SetCreator(OTF2_Archive *archive, const char *creator)
Set creator.
struct OTF2_GlobalSnapReader_struct OTF2_GlobalSnapReader
OTF2 global snap reader handle.
Definition: OTF2_GeneralDefinitions.h:264
This is the local event reader, which reads events from one location.
OTF2_GlobalDefReader * OTF2_Archive_GetGlobalDefReader(OTF2_Archive *archive)
Get a global definition reader.
struct OTF2_Archive_struct OTF2_Archive
Keeps all meta-data for an OTF2 archive.
Definition: OTF2_Archive.h:210
OTF2_ErrorCode OTF2_Archive_CloseSnapReader(OTF2_Archive *archive, OTF2_SnapReader *reader)
Close an opened local snap reader.
OTF2_ErrorCode OTF2_Archive_CloseEvtWriter(OTF2_Archive *archive, OTF2_EvtWriter *writer)
Close an opened local event writer.
OTF2_ErrorCode OTF2_Archive_SelectLocation(OTF2_Archive *archive, OTF2_LocationRef location)
Select a location to be read.
struct OTF2_DefReader_struct OTF2_DefReader
OTF2 local definition reader handle.
Definition: OTF2_GeneralDefinitions.h:252
OTF2_ErrorCode OTF2_Archive_SetMachineName(OTF2_Archive *archive, const char *machineName)
Set machine name.
OTF2_ErrorCode OTF2_Archive_GetMachineName(OTF2_Archive *archive, char **machineName)
Get machine name.
OTF2_ErrorCode OTF2_Archive_SetProperty(OTF2_Archive *archive, const char *name, const char *value, bool overwrite)
Add or remove a trace file property to this archive.
This is the local snap reader, which reads snapshot events from one location.
Struct which holds all locking callbacks.
Definition: OTF2_Callbacks.h:636
OTF2_ErrorCode OTF2_Archive_CloseDefReader(OTF2_Archive *archive, OTF2_DefReader *reader)
Close an opened local definition reader.
OTF2_ErrorCode OTF2_Archive_GetNumberOfGlobalDefinitions(OTF2_Archive *archive, uint64_t *numberOfDefinitions)
Get the number of global definitions.
OTF2_DefReader * OTF2_Archive_GetDefReader(OTF2_Archive *archive, OTF2_LocationRef location)
Get a local definition reader.
uint8_t OTF2_FileSubstrate
Wrapper for enum OTF2_FileSubstrate_enum.
Definition: OTF2_GeneralDefinitions.h:464
This header file provides all user callbacks.
OTF2_SnapReader * OTF2_Archive_GetSnapReader(OTF2_Archive *archive, OTF2_LocationRef location)
Get a local snap reader.
uint8_t OTF2_Compression
Defines which compression is used. Please see OTF2_Compression_enum for a detailed description...
Definition: OTF2_GeneralDefinitions.h:301
This is the global event reader.
OTF2_ErrorCode OTF2_Archive_GetCreator(OTF2_Archive *archive, char **creator)
Get creator information.
struct OTF2_GlobalDefWriter_struct OTF2_GlobalDefWriter
Typedef of the struct which keeps all necessary information of a global definition writer...
Definition: OTF2_GlobalDefWriter.h:71
OTF2_ErrorCode OTF2_Archive_OpenEvtFiles(OTF2_Archive *archive)
Open the events file container.
struct OTF2_EvtWriter_struct OTF2_EvtWriter
Keeps all necessary information about the event writer. See OTF2_EvtWriter_struct for detailed inform...
Definition: OTF2_EvtWriter.h:63
Structure holding the memory callbacks.
Definition: OTF2_Callbacks.h:239
struct OTF2_SnapWriter_struct OTF2_SnapWriter
Keeps all necessary information about the snap writer. See OTF2_SnapWriter_struct for detailed inform...
Definition: OTF2_SnapWriter.h:47
This lowest user-visible layer provides write routines to write event data of a single location...
OTF2_ErrorCode OTF2_Archive_CloseMarkerReader(OTF2_Archive *archive, OTF2_MarkerReader *markerReader)
Closes the marker reader.
OTF2_Archive * OTF2_Archive_Open(const char *archivePath, const char *archiveName, const OTF2_FileMode fileMode, const uint64_t chunkSizeEvents, const uint64_t chunkSizeDefs, const OTF2_FileSubstrate fileSubstrate, const OTF2_Compression compression)
Create a new archive.
struct OTF2_CollectiveContext OTF2_CollectiveContext
User provided type for collective groups.
Definition: OTF2_Callbacks.h:303
OTF2_ErrorCode OTF2_Archive_SetCollectiveCallbacks(OTF2_Archive *archive, const OTF2_CollectiveCallbacks *collectiveCallbacks, void *collectiveData, OTF2_CollectiveContext *globalCommContext, OTF2_CollectiveContext *localCommContext)
Set the collective callbacks for the archive.
OTF2_ErrorCode OTF2_Archive_CloseDefWriter(OTF2_Archive *archive, OTF2_DefWriter *writer)
Close an opened local definition writer.
OTF2_ErrorCode OTF2_Archive_GetNumberOfLocations(OTF2_Archive *archive, uint64_t *numberOfLocations)
Get the number of locations.
OTF2_ErrorCode OTF2_Archive_CloseEvtReader(OTF2_Archive *archive, OTF2_EvtReader *reader)
Close an opened local event reader.
This file provides all routines that write marker records.
This lowest user-visible layer provides write routines to write snapshot records for a single locatio...
uint8_t OTF2_FileMode
Defines how to interact with files. Please see OTF2_FileMode_enum for a detailed description.
Definition: OTF2_GeneralDefinitions.h:284
OTF2_ErrorCode OTF2_Archive_GetNumberOfSnapshots(OTF2_Archive *archive, uint32_t *number)
Get the number of snapshots.
OTF2_ErrorCode OTF2_Archive_GetPropertyNames(OTF2_Archive *archive, uint32_t *numberOfProperties, char ***names)
Get the names of all trace file properties.
OTF2_ErrorCode OTF2_Archive_SetHint(OTF2_Archive *archive, OTF2_Hint hint, void *value)
Set the hint in the archive to the given value.
struct OTF2_ThumbWriter_struct OTF2_ThumbWriter
Keeps all necessary information about the thumb writer. See OTF2_ThumbWriter_struct for detailed info...
Definition: OTF2_Thumbnail.h:38
Error codes and error handling.
struct OTF2_EvtReader_struct OTF2_EvtReader
OTF2 local event reader handle.
Definition: OTF2_GeneralDefinitions.h:244
OTF2_ErrorCode OTF2_Archive_SetNumberOfSnapshots(OTF2_Archive *archive, uint32_t number)
Set the number of snapshots.
OTF2_DefWriter * OTF2_Archive_GetDefWriter(OTF2_Archive *archive, OTF2_LocationRef location)
Get a local definition writer.
OTF2_ThumbWriter * OTF2_Archive_GetThumbWriter(OTF2_Archive *archive, const char *name, const char *description, OTF2_ThumbnailType type, uint32_t numberOfSamples, uint32_t numberOfMetrics, const uint64_t *refsToDefs)
Get a thumb writer.
struct OTF2_GlobalEvtReader_struct OTF2_GlobalEvtReader
OTF2 global event reader handle.
Definition: OTF2_GeneralDefinitions.h:248
OTF2_ErrorCode OTF2_Archive_CloseSnapWriter(OTF2_Archive *archive, OTF2_SnapWriter *writer)
Close an opened local snap writer.
This is the global snapshot event reader.