2.0 (revision 4611)
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 
157 #include <stdint.h>
158 
159 
160 #include <otf2/OTF2_ErrorCodes.h>
161 
162 
163 #include <otf2/OTF2_Callbacks.h>
164 #include <otf2/OTF2_DefWriter.h>
165 #include <otf2/OTF2_DefReader.h>
166 #include <otf2/OTF2_EvtWriter.h>
167 #include <otf2/OTF2_EvtReader.h>
168 #include <otf2/OTF2_SnapWriter.h>
169 #include <otf2/OTF2_SnapReader.h>
174 #include <otf2/OTF2_Thumbnail.h>
175 #include <otf2/OTF2_MarkerWriter.h>
176 #include <otf2/OTF2_MarkerReader.h>
177 
178 
179 #ifdef __cplusplus
180 extern "C" {
181 #endif /* __cplusplus */
182 
183 
189 #define OTF2_CHUNK_SIZE_EVENTS_DEFAULT ( 1024 * 1024 )
190 
191 
197 #define OTF2_CHUNK_SIZE_DEFINITIONS_DEFAULT ( 4 * 1024 * 1024 )
198 
199 
205 typedef struct OTF2_Archive_struct OTF2_Archive;
206 
207 
267 OTF2_Archive_Open( const char* archivePath,
268  const char* archiveName,
269  const OTF2_FileMode fileMode,
270  const uint64_t chunkSizeEvents,
271  const uint64_t chunkSizeDefs,
272  const OTF2_FileSubstrate fileSubstrate,
273  const OTF2_Compression compression );
274 
275 
287 OTF2_Archive_Close( OTF2_Archive* archive );
288 
289 
306  OTF2_FileMode newFileMode );
307 
308 
327  uint64_t chunkSize );
328 
329 
343  const char* machineName );
344 
345 
359  const char* description );
360 
361 
375  const char* creator );
376 
377 
389  const OTF2_FlushCallbacks* flushCallbacks,
390  void* flushData );
391 
392 
404  const OTF2_MemoryCallbacks* memoryCallbacks,
405  void* memoryData );
406 
407 
423  const OTF2_CollectiveCallbacks* collectiveCallbacks,
424  void* collectiveData,
425  OTF2_CollectiveContext* globalCommContext,
426  OTF2_CollectiveContext* localCommContext );
427 
428 
438 
439 
461  const OTF2_LockingCallbacks* lockingCallbacks,
462  void* lockingData );
463 
464 
492  OTF2_Hint hint,
493  void* value );
494 
495 
522  const char* name,
523  const char* value,
524  bool overwrite );
525 
526 
550  const char* name,
551  bool value,
552  bool overwrite );
553 
554 
567  uint32_t* numberOfProperties,
568  char*** names );
569 
570 
586  const char* name,
587  char** value );
588 
589 
602  uint64_t* id );
603 
604 
614  uint64_t* numberOfLocations );
615 
616 
626  uint64_t* numberOfDefinitions );
627 
628 
638  char** machineName );
639 
640 
650  char** description );
651 
652 
662  char** creator );
663 
664 
676  uint8_t* major,
677  uint8_t* minor,
678  uint8_t* bugfix );
679 
680 
691  uint64_t* chunkSizeEvents,
692  uint64_t* chunkSizeDefs );
693 
694 
704  OTF2_FileSubstrate* substrate );
705 
706 
716  OTF2_Compression* compression );
717 
718 
729  OTF2_LocationRef location );
730 
731 
742  OTF2_LocationRef location );
743 
744 
756 
757 
770  OTF2_LocationRef location );
771 
772 
792  const char* name,
793  const char* description,
794  OTF2_ThumbnailType type,
795  uint32_t numberOfSamples,
796  uint32_t numberOfMetrics,
797  const uint64_t* refsToDefs );
798 
799 
811 
812 
823  OTF2_LocationRef location );
824 
825 
835 
836 
847  OTF2_LocationRef location );
848 
849 
859 
860 
873  OTF2_LocationRef location );
874 
875 
887 
888 
901  uint32_t number );
902 
903 
915 
916 
926  OTF2_EvtWriter* writer );
927 
928 
938  OTF2_DefWriter* writer );
939 
940 
952  OTF2_MarkerWriter* writer );
953 
954 
966  OTF2_SnapWriter* writer );
967 
968 
986  OTF2_GlobalDefWriter* writer );
987 
988 
998  OTF2_EvtReader* reader );
999 
1000 
1012  OTF2_ThumbReader* reader );
1013 
1014 
1026  OTF2_GlobalEvtReader* globalEvtReader );
1027 
1028 
1038  OTF2_DefReader* reader );
1039 
1040 
1050  OTF2_GlobalDefReader* globalDefReader );
1051 
1052 
1064  OTF2_SnapReader* reader );
1065 
1066 
1079  OTF2_GlobalSnapReader* globalSnapReader );
1080 
1081 
1093  OTF2_MarkerReader* markerReader );
1094 
1095 
1108  uint32_t* number );
1109 
1110 
1123  uint32_t number );
1124 
1125 
1138  uint32_t* number );
1139 
1140 
1154 
1155 
1169 
1170 
1184 
1185 
1199 
1200 
1214 
1215 
1229 
1230 
1243  OTF2_LocationRef location );
1244 
1245 
1246 #ifdef __cplusplus
1247 }
1248 #endif /* __cplusplus */
1249 
1250 
1251 #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:242
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:230
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:125
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:355
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:485
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_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:877
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:234
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:238
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:205
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:226
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:631
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:438
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:275
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:300
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:258
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:218
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:222
OTF2_ErrorCode OTF2_Archive_CloseSnapWriter(OTF2_Archive *archive, OTF2_SnapWriter *writer)
Close an opened local snap writer.
This is the global snapshot event reader.