3.0-rc2 (revision 337012f1)
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, 2021,
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 
169 #include <stdint.h>
170 
171 
172 #include "otf2_compiler.h"
173 
174 
175 #include <otf2/OTF2_ErrorCodes.h>
176 
177 
178 #include <otf2/OTF2_Callbacks.h>
179 #include <otf2/OTF2_DefWriter.h>
180 #include <otf2/OTF2_DefReader.h>
181 #include <otf2/OTF2_EvtWriter.h>
182 #include <otf2/OTF2_EvtReader.h>
183 #include <otf2/OTF2_SnapWriter.h>
184 #include <otf2/OTF2_SnapReader.h>
189 #include <otf2/OTF2_Thumbnail.h>
190 #include <otf2/OTF2_MarkerWriter.h>
191 #include <otf2/OTF2_MarkerReader.h>
192 
193 
194 #ifdef __cplusplus
195 extern "C" {
196 #endif /* __cplusplus */
197 
198 
204 #define OTF2_CHUNK_SIZE_EVENTS_DEFAULT ( 1024 * 1024 )
205 
206 
212 #define OTF2_CHUNK_SIZE_DEFINITIONS_DEFAULT ( 4 * 1024 * 1024 )
213 
214 
220 typedef struct OTF2_Archive_struct OTF2_Archive;
221 
222 
282 OTF2_Archive_Open( const char* archivePath,
283  const char* archiveName,
284  const OTF2_FileMode fileMode,
285  const uint64_t chunkSizeEvents,
286  const uint64_t chunkSizeDefs,
287  const OTF2_FileSubstrate fileSubstrate,
288  const OTF2_Compression compression );
289 
290 
302 OTF2_Archive_Close( OTF2_Archive* archive );
303 
304 
321  OTF2_FileMode newFileMode );
322 
323 
342  uint64_t chunkSize );
343 
344 
358  const char* machineName );
359 
360 
374  const char* description );
375 
376 
390  const char* creator );
391 
392 
404  const OTF2_FlushCallbacks* flushCallbacks,
405  void* flushData );
406 
407 
419  const OTF2_MemoryCallbacks* memoryCallbacks,
420  void* memoryData );
421 
422 
438  const OTF2_CollectiveCallbacks* collectiveCallbacks,
439  void* collectiveData,
440  OTF2_CollectiveContext* globalCommContext,
441  OTF2_CollectiveContext* localCommContext );
442 
443 
453 
454 
465  bool* result );
466 
467 
479  bool* result );
480 
481 
503  const OTF2_LockingCallbacks* lockingCallbacks,
504  void* lockingData );
505 
506 
534  OTF2_Hint hint,
535  void* value );
536 
537 
564  const char* name,
565  const char* value,
566  bool overwrite );
567 
568 
592  const char* name,
593  bool value,
594  bool overwrite );
595 
596 
609  uint32_t* numberOfProperties,
610  char*** names );
611 
612 
628  const char* name,
629  char** value );
630 
631 
644  uint64_t* id );
645 
646 
656  uint64_t* numberOfLocations );
657 
658 
668  uint64_t* numberOfDefinitions );
669 
670 
680  char** machineName );
681 
682 
692  char** description );
693 
694 
704  char** creator );
705 
706 
718  uint8_t* major,
719  uint8_t* minor,
720  uint8_t* bugfix );
721 
722 
733  uint64_t* chunkSizeEvents,
734  uint64_t* chunkSizeDefs );
735 
736 
746  OTF2_FileSubstrate* substrate );
747 
748 
758  OTF2_Compression* compression );
759 
760 
771  OTF2_LocationRef location );
772 
773 
784  OTF2_LocationRef location );
785 
786 
798 
799 
812  OTF2_LocationRef location );
813 
814 
834  const char* name,
835  const char* description,
836  OTF2_ThumbnailType type,
837  uint32_t numberOfSamples,
838  uint32_t numberOfMetrics,
839  const uint64_t* refsToDefs );
840 
841 
853 
854 
865  OTF2_LocationRef location );
866 
867 
877 
878 
889  OTF2_LocationRef location );
890 
891 
901 
902 
915  OTF2_LocationRef location );
916 
917 
929 
930 
943  uint32_t number );
944 
945 
957 
958 
968  OTF2_EvtWriter* writer );
969 
970 
980  OTF2_DefWriter* writer );
981 
982 
994  OTF2_MarkerWriter* writer );
995 
996 
1008  OTF2_SnapWriter* writer );
1009 
1010 
1028  OTF2_GlobalDefWriter* writer );
1029 
1030 
1040  OTF2_EvtReader* reader );
1041 
1042 
1054  OTF2_ThumbReader* reader );
1055 
1056 
1068  OTF2_GlobalEvtReader* globalEvtReader );
1069 
1070 
1080  OTF2_DefReader* reader );
1081 
1082 
1092  OTF2_GlobalDefReader* globalDefReader );
1093 
1094 
1106  OTF2_SnapReader* reader );
1107 
1108 
1121  OTF2_GlobalSnapReader* globalSnapReader );
1122 
1123 
1135  OTF2_MarkerReader* markerReader );
1136 
1137 
1150  uint32_t* number );
1151 
1152 
1165  uint32_t number );
1166 
1167 
1180  uint32_t* number );
1181 
1182 
1196 
1197 
1211 
1212 
1226 
1227 
1241 
1242 
1256 
1257 
1271 
1272 
1285  OTF2_LocationRef location );
1286 
1287 
1288 #ifdef __cplusplus
1289 }
1290 #endif /* __cplusplus */
1291 
1292 
1293 #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:271
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:259
OTF2_ErrorCode OTF2_Archive_IsMaster(OTF2_Archive *archive, bool *result)
Same as OTF2_Archive_IsPrimary.
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:142
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_IsPrimary(OTF2_Archive *archive, bool *result)
Determines if this archive is the primary archive which handles the global archive state (anchor file...
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:386
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:497
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:152
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:66
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:1039
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:263
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:267
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:220
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.
Compiler feature test macros.
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:255
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:643
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:477
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:304
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:75
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:66
Structure holding the memory callbacks.
Definition: OTF2_Callbacks.h:246
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:50
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:310
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:287
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:247
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:251
OTF2_ErrorCode OTF2_Archive_CloseSnapWriter(OTF2_Archive *archive, OTF2_SnapWriter *writer)
Close an opened local snap writer.
This is the global snapshot event reader.