OpenMPI  0.1.1
OTFAUX_Thumbnail.h
Go to the documentation of this file.
1 #ifndef OTFAUX_THUMBNAIL_H
2 #define OTFAUX_THUMBNAIL_H
3 
4 #include <otf.h>
5 
6 /**
7  * @file otfauxlib/OTFAUX_Thumbnail.h
8  *
9  * @brief Provides a module to collect data for thumbnail generation.
10  */
11 
12 #ifdef __cplusplus
13 extern "C" {
14 #endif /* __cplusplus */
15 
16 /**
17  * @defgroup thumbnail Module for thumbnail generation.
18  *
19  * @usage:
20  *
21  * ctx = OTFAUX_Thumbnail_Create(minTime, maxTime, 1024);
22  *
23  * announce all interesting processes:
24  * OTFAUX_Thumbnail_declareProcess(ctx, ...);
25  *
26  * repeatedly call for interesting processes:
27  * OTFAUX_Thumbnail_handleEnter(ctx, ...);
28  * OTFAUX_Thumbnail_handleLeave(ctx, ...);
29  *
30  * at end, for all processes:
31  * OTFAUX_ThumbnailData td;
32  * OTFAUX_Thumbnail_getData(ctx, process, &td);
33  * .. do something with td.start_pixel and td.function ..
34  *
35  * OTFAUX_Thumbnail_Destroy(ctx);
36  *
37  * @{
38  */
39 
40 /** Opaque type for using the thumbnail module. */
42 
43 /**
44  * Create a context for thumbnail generation.
45  *
46  * @param minTime Minimum timestamp of the trace file.
47  * @param maxTime Maximum timestamp of the trace file.
48  * @param width The width in pixels of the thumbnail.
49  *
50  * @return The context.
51  */
53 OTFAUX_Thumbnail_create( uint64_t minTime,
54  uint64_t maxTime,
55  uint32_t width );
56 
57 /**
58  * Destroy a context previously created with @a OTFAUX_Thumbnail_Create.
59  *
60  * @param tn_context The context.
61  */
62 void
64 
65 /**
66  * Declares that the process @a process should be handled by this context.
67  *
68  * @param tn_context The context.
69  */
70 void
72  uint64_t process );
73 
74 /**
75  * Declare that the process @a process has entered the fucntion @a function
76  * at timestamp @a timestamp.
77  *
78  * This function needs to be called in monotonically increasing timestamp order.
79  *
80  * @param tn_context The context.
81  * @param timestamp The timestamp.
82  * @param process The process.
83  * @param function The function.
84  */
85 void
87  uint64_t timestamp,
88  uint64_t process,
89  uint32_t function );
90 
91 /**
92  * Declare that the process @a process has left the current fucntion at
93  * timestamp @a timestamp.
94  *
95  * This function needs to be called in monotonically increasing timestamp order.
96  *
97  * @param tn_context The context.
98  * @param timestamp The timestamp.
99  * @param process The process.
100  */
101 void
103  uint64_t timestamp,
104  uint64_t process );
105 
106 /**
107  * Get the number of entries for the process @a process.
108  *
109  * @param tn_context The context.
110  *
111  * @param The size.
112  */
113 uint32_t
115  uint64_t process );
116 
117 typedef struct {
118  uint32_t* start_pixel;
119  uint32_t* function;
120  uint32_t size;
122 
123 /**
124  * Get the collected thumbnail data for process @a process.
125  *
126  * @param tn_context The context.
127  * @param process The process.
128  * @param data Pointer to storage where the data will be stored into.
129  * @param size Pointer to storage where the size will be stored into.
130  *
131  * @param 1 on success.
132  */
133 int
135  uint64_t process,
136  OTFAUX_Thumbnail_Data* data );
137 
138 /**
139  * @}
140  */
141 
142 char*
143 OTFAUX_Thumbnail_getFilename( const char* namestub,
144  size_t length,
145  char* name_buffer );
146 
147 /**
148  * @defgroup thumbnailwriter Module to write a thumbnail.
149  *
150  * @usage:
151  *
152  * writer = OTFAUX_ThumbnailWriter_create("foo.otf", 512, 1024, ...);
153  *
154  * for each process:
155  * OTFAUX_ThumbnailData td;
156  * OTFAUX_Thumbnail_getData( ctx, process, &td );
157  * OTFAUX_ThumbnailWriter_writeProcess( writer, process, &td );
158  *
159  * OTFAUX_ThumbnailWriter_destroy( writer );
160  */
161 
163 
165 OTFAUX_ThumbnailWriter_create( const char* filename,
166  uint32_t height,
167  uint32_t width,
168  OTF_FileManager* manager );
169 
170 int
171 OTFAUX_ThumbnailWriter_destroy( OTFAUX_ThumbnailWriter* tn_writer );
172 
173 int
174 OTFAUX_ThumbnailWriter_close( OTFAUX_ThumbnailWriter* tn_writer );
175 
176 int
177 OTFAUX_ThumbnailWriter_writeProcess( OTFAUX_ThumbnailWriter* tn_writer,
178  uint64_t process,
179  OTFAUX_Thumbnail_Data* data );
180 
181 /**
182  * @}
183  */
184 
185 
186 /**
187  * @defgroup thumbnailreader Module to read a thumbnail.
188  */
189 
191 
193 OTFAUX_ThumbnailReader_create( const char* filename,
194  OTF_FileManager* manager );
195 
196 int
197 OTFAUX_ThumbnailReader_destroy( OTFAUX_ThumbnailReader* tn_reader );
198 
199 int
200 OTFAUX_ThumbnailReader_close( OTFAUX_ThumbnailReader* tn_reader );
201 
202 int
203 OTFAUX_ThumbnailReader_getDimension( OTFAUX_ThumbnailReader* tn_reader,
204  uint32_t* height,
205  uint32_t* width );
206 
207 int
208 OTFAUX_ThumbnailReader_read( OTFAUX_ThumbnailReader* tn_reader,
209  void ( *process_handler )( void*,
210  uint64_t,
211  uint32_t,
212  uint32_t ),
213  void* data );
214 
215 
216 /**
217  * @}
218  */
219 
220 
221 #ifdef __cplusplus
222 }
223 #endif /* __cplusplus */
224 
225 #endif /* OTFAUX_THUMBNAIL_H */
Main include file for applications using OTF.
void OTFAUX_Thumbnail_handleLeave(OTFAUX_Thumbnail_Context *tn_context, uint64_t timestamp, uint64_t process)
Declare that the process process has left the current fucntion at timestamp timestamp.
Definition: OTFAUX_Thumbnail.c:169
Definition: OTFAUX_Thumbnail.c:240
Definition: OTFAUX_Thumbnail.c:376
uint32_t OTFAUX_Thumbnail_getSize(OTFAUX_Thumbnail_Context *context, uint64_t process)
Get the number of entries for the process process.
Definition: OTFAUX_Thumbnail.c:188
Definition: OTFAUX_Thumbnail.c:39
OTFAUX_Thumbnail_Context * OTFAUX_Thumbnail_create(uint64_t minTime, uint64_t maxTime, uint32_t width)
Create a context for thumbnail generation.
Definition: OTFAUX_Thumbnail.c:48
void OTFAUX_Thumbnail_handleEnter(OTFAUX_Thumbnail_Context *tn_context, uint64_t timestamp, uint64_t process, uint32_t function)
Declare that the process process has entered the fucntion function at timestamp timestamp.
Definition: OTFAUX_Thumbnail.c:138
Definition: OTFAUX_Thumbnail.h:117
void OTFAUX_Thumbnail_declareProcess(OTFAUX_Thumbnail_Context *tn_context, uint64_t process)
Declares that the process process should be handled by this context.
Definition: OTFAUX_Thumbnail.c:123
void OTFAUX_Thumbnail_destroy(OTFAUX_Thumbnail_Context *tn_context)
Destroy a context previously created with OTFAUX_Thumbnail_Create.
Definition: OTFAUX_Thumbnail.c:60
file handles management structure
Definition: OTF_FileManager.c:32
int OTFAUX_Thumbnail_getData(OTFAUX_Thumbnail_Context *context, uint64_t process, OTFAUX_Thumbnail_Data *data)
Get the collected thumbnail data for process process.
Definition: OTFAUX_Thumbnail.c:204