Babeltrace python binding
[babeltrace.git] / bindings / python / babeltrace.i.in
1 /*
2 * babeltrace.i.in
3 *
4 * Babeltrace Python Module interface file
5 *
6 * Copyright 2012 EfficiOS Inc.
7 *
8 * Author: Danny Serres <danny.serres@efficios.com>
9 *
10 * Permission is hereby granted, free of charge, to any person obtaining a copy
11 * of this software and associated documentation files (the "Software"), to deal
12 * in the Software without restriction, including without limitation the rights
13 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14 * copies of the Software, and to permit persons to whom the Software is
15 * furnished to do so, subject to the following conditions:
16 *
17 * The above copyright notice and this permission notice shall be included in
18 * all copies or substantial portions of the Software.
19 */
20
21
22 %define DOCSTRING
23 "BABELTRACE_VERSION_STR
24
25 Babeltrace is a trace viewer and converter reading and writing the
26 Common Trace Format (CTF). Its main use is to pretty-print CTF
27 traces into a human-readable text output.
28
29 To use this module, the first step is to create a Context and add a
30 trace to it."
31 %enddef
32
33 %module(docstring=DOCSTRING) babeltrace
34
35 %include "typemaps.i"
36 %{
37 #define SWIG_FILE_WITH_INIT
38 #include <babeltrace/babeltrace.h>
39 #include <babeltrace/babeltrace-internal.h>
40 #include <babeltrace/trace-handle.h>
41 #include <babeltrace/trace-handle-internal.h>
42 #include <babeltrace/context.h>
43 #include <babeltrace/context-internal.h>
44 #include <babeltrace/iterator.h>
45 #include <babeltrace/iterator-internal.h>
46 #include <babeltrace/format.h>
47 #include <babeltrace/list.h>
48 #include <babeltrace/uuid.h>
49 #include <babeltrace/types.h>
50 #include <babeltrace/ctf/iterator.h>
51 #include "python-complements.h"
52 %}
53
54 typedef unsigned long long uint64_t;
55 typedef long long int64_t;
56 typedef int bt_intern_str;
57
58 /* =================================================================
59 CONTEXT.H, CONTEXT-INTERNAL.H
60 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
61 */
62
63 %rename("_bt_context_create") bt_context_create(void);
64 %rename("_bt_context_add_trace") bt_context_add_trace(
65 struct bt_context *ctx, const char *path, const char *format,
66 void (*packet_seek)(struct stream_pos *pos, size_t index, int whence),
67 struct mmap_stream_list *stream_list, FILE *metadata);
68 %rename("_bt_context_remove_trace") bt_context_remove_trace(
69 struct bt_context *ctx, int trace_id);
70 %rename("_bt_context_get") bt_context_get(struct bt_context *ctx);
71 %rename("_bt_context_put") bt_context_put(struct bt_context *ctx);
72 %rename("_bt_ctf_event_get_context") bt_ctf_event_get_context(
73 const struct bt_ctf_event *event);
74
75 struct bt_context *bt_context_create(void);
76 int bt_context_add_trace(struct bt_context *ctx, const char *path, const char *format,
77 void (*packet_seek)(struct stream_pos *pos, size_t index, int whence),
78 struct mmap_stream_list *stream_list, FILE *metadata);
79 void bt_context_remove_trace(struct bt_context *ctx, int trace_id);
80 void bt_context_get(struct bt_context *ctx);
81 void bt_context_put(struct bt_context *ctx);
82 struct bt_context *bt_ctf_event_get_context(const struct bt_ctf_event *event);
83
84 // class Context to prevent direct access to struct bt_context
85 %pythoncode%{
86 class Context:
87 """
88 The context represents the object in which a trace_collection is
89 open. As long as this structure is allocated, the trace_collection
90 is open and the traces it contains can be read and seeked by the
91 iterators and callbacks.
92 """
93
94 def __init__(self):
95 self._c = _bt_context_create()
96
97 def __del__(self):
98 _bt_context_put(self._c)
99
100 def add_trace(self, path, format_str,
101 packet_seek=None, stream_list=None, metadata=None):
102 """
103 Add a trace by path to the context.
104
105 Open a trace.
106
107 path is the path to the trace, it is not recursive.
108 If "path" is None, stream_list is used instead as a list
109 of mmap streams to open for the trace.
110
111 format is a string containing the format name in which the trace was
112 produced.
113
114 packet_seek is not implemented for Python. Should be left None to
115 use the default packet_seek handler provided by the trace format.
116
117 stream_list is a linked list of streams, it is used to open a trace
118 where the trace data is located in memory mapped areas instead of
119 trace files, this argument should be None when path is not None.
120
121 The metadata parameter acts as a metadata override when not None,
122 otherwise the format handles the metadata opening.
123
124 Return: the corresponding TraceHandle on success or None on error.
125 """
126 if metadata is not None:
127 metadata = metadata._file
128
129 ret = _bt_context_add_trace(self._c, path, format_str, packet_seek,
130 stream_list, metadata)
131 if ret < 0:
132 return None
133
134 th = TraceHandle.__new__(TraceHandle)
135 th._id = ret
136 return th
137
138 def add_traces_recursive(self, path, format_str):
139 """
140 Open a trace recursively.
141
142 Find each trace present in the subdirectory starting from the given
143 path, and add them to the context.
144
145 Return a dict of TraceHandle instances (the full path is the key).
146 Return None on error.
147 """
148
149 import os
150
151 trace_handles = {}
152
153 noTrace = True
154 error = False
155
156 for fullpath, dirs, files in os.walk(path):
157 if "metadata" in files:
158 trace_handle = self.add_trace(fullpath, format_str)
159 if trace_handle is None:
160 error = True
161 continue
162
163 trace_handles[fullpath] = trace_handle
164 noTrace = False
165
166 if noTrace and error:
167 return None
168 return trace_handles
169
170 def remove_trace(self, trace_handle):
171 """
172 Remove a trace from the context.
173 Effectively closing the trace.
174 """
175 try:
176 _bt_context_remove_trace(self._c, trace_handle._id)
177 except AttributeError:
178 raise TypeError("in remove_trace, "
179 "argument 2 must be a TraceHandle instance")
180 %}
181
182
183
184 /* =================================================================
185 FORMAT.H, REGISTRY
186 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
187 */
188
189 %rename("lookup_format") bt_lookup_format(bt_intern_str qname);
190 %rename("_bt_print_format_list") bt_fprintf_format_list(FILE *fp);
191 %rename("register_format") bt_register_format(struct format *format);
192
193 extern struct format *bt_lookup_format(bt_intern_str qname);
194 extern void bt_fprintf_format_list(FILE *fp);
195 extern int bt_register_format(struct format *format);
196
197 void format_init(void);
198 void format_finalize(void);
199
200 %pythoncode %{
201
202 def print_format_list(babeltrace_file):
203 """
204 Print a list of available formats to file.
205
206 babeltrace_file must be a File instance opened in write mode.
207 """
208 try:
209 if babeltrace_file._file is not None:
210 _bt_print_format_list(babeltrace_file._file)
211 except AttributeError:
212 raise TypeError("in print_format_list, "
213 "argument 1 must be a File instance")
214
215 %}
216
217
218 /* =================================================================
219 ITERATOR.H, ITERATOR-INTERNAL.H
220 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
221 */
222
223 %rename("_bt_iter_create") bt_iter_create(struct bt_context *ctx,
224 const struct bt_iter_pos *begin_pos, const struct bt_iter_pos *end_pos);
225 %rename("_bt_iter_destroy") bt_iter_destroy(struct bt_iter *iter);
226 %rename("_bt_iter_next") bt_iter_next(struct bt_iter *iter);
227 %rename("_bt_iter_get_pos") bt_iter_get_pos(struct bt_iter *iter);
228 %rename("_bt_iter_free_pos") bt_iter_free_pos(struct bt_iter_pos *pos);
229 %rename("_bt_iter_set_pos") bt_iter_set_pos(struct bt_iter *iter,
230 const struct bt_iter_pos *pos);
231 %rename("_bt_iter_create_time_pos") bt_iter_create_time_pos(struct bt_iter *iter,
232 uint64_t timestamp);
233
234 struct bt_iter *bt_iter_create(struct bt_context *ctx,
235 const struct bt_iter_pos *begin_pos, const struct bt_iter_pos *end_pos);
236 void bt_iter_destroy(struct bt_iter *iter);
237 int bt_iter_next(struct bt_iter *iter);
238 struct bt_iter_pos *bt_iter_get_pos(struct bt_iter *iter);
239 void bt_iter_free_pos(struct bt_iter_pos *pos);
240 int bt_iter_set_pos(struct bt_iter *iter, const struct bt_iter_pos *pos);
241 struct bt_iter_pos *bt_iter_create_time_pos(struct bt_iter *iter, uint64_t timestamp);
242
243 %rename("_bt_iter_pos") bt_iter_pos;
244 %rename("SEEK_TIME") BT_SEEK_TIME;
245 %rename("SEEK_RESTORE") BT_SEEK_RESTORE;
246 %rename("SEEK_CUR") BT_SEEK_CUR;
247 %rename("SEEK_BEGIN") BT_SEEK_BEGIN;
248 %rename("SEEK_END") BT_SEEK_END;
249
250
251 // This struct is taken from iterator.h
252 // All changes to the struct must also be made here
253 struct bt_iter_pos {
254 enum {
255 BT_SEEK_TIME, /* uses u.seek_time */
256 BT_SEEK_RESTORE, /* uses u.restore */
257 BT_SEEK_CUR,
258 BT_SEEK_BEGIN,
259 BT_SEEK_END,
260 } type;
261 union {
262 uint64_t seek_time;
263 struct bt_saved_pos *restore;
264 } u;
265 };
266
267
268 %pythoncode%{
269
270 class IterPos:
271 """This class represents the position where to set an iterator."""
272
273 __can_access = False
274
275 def __init__(self, seek_type, seek_time = None):
276 """
277 seek_type represents the type of seek to use.
278 seek_time is the timestamp to seek to when using SEEK_TIME, it
279 is expressed in nanoseconds
280 Only use SEEK_RESTORE on IterPos obtained from the get_pos function
281 in Iter class.
282 """
283
284 self._pos = _bt_iter_pos()
285 self._pos.type = seek_type
286 if seek_time and seek_type == SEEK_TIME:
287 self._pos.u.seek_time = seek_time
288 self.__can_access = True
289
290 def __del__(self):
291 if not self.__can_access:
292 _bt_iter_free_pos(self._pos)
293
294 def _get_type(self):
295 if not __can_access:
296 raise AttributeError("seek_type is not available")
297 return self._pos.type
298
299 def _set_type(self, seek_type):
300 if not __can_access:
301 raise AttributeError("seek_type is not available")
302 self._pos.type = seek_type
303
304 def _get_time(self):
305 if not __can_access:
306 raise AttributeError("seek_time is not available")
307
308 elif self._pos.type is not SEEK_TIME:
309 raise TypeError("seek_type is not SEEK_TIME")
310
311 return self._pos.u.seek_time
312
313 def _set_time(self, time):
314 if not __can_access:
315 raise AttributeError("seek_time is not available")
316
317 elif self._pos.type is not SEEK_TIME:
318 raise TypeError("seek_type is not SEEK_TIME")
319
320 self._pos.u.seek_time = time
321
322 def _get_pos(self):
323 return self._pos
324
325
326 seek_type = property(_get_type, _set_type)
327 seek_time = property(_get_time, _set_time)
328
329
330 class Iterator:
331
332 __with_init = False
333
334 def __init__(self, context, begin_pos = None, end_pos = None, _no_init = None):
335 """
336 Allocate a trace collection iterator.
337
338 begin_pos and end_pos are optional parameters to specify the
339 position at which the trace collection should be seeked upon
340 iterator creation, and the position at which iteration will
341 start returning "EOF".
342
343 By default, if begin_pos is None, a BT_SEEK_CUR is performed at
344 creation. By default, if end_pos is None, a BT_SEEK_END (end of
345 trace) is the EOF criterion.
346 """
347 if _no_init is None:
348 if begin_pos is None:
349 bp = None
350 else:
351 try:
352 bp = begin_pos._pos
353 except AttributeError:
354 raise TypeError("in __init__, "
355 "argument 3 must be a IterPos instance")
356
357 if end_pos is None:
358 ep = None
359 else:
360 try:
361 ep = end_pos._pos
362 except AttributeError:
363 raise TypeError("in __init__, "
364 "argument 4 must be a IterPos instance")
365
366 try:
367 self._bi = _bt_iter_create(context._c, bp, ep)
368 except AttributeError:
369 raise TypeError("in __init__, "
370 "argument 2 must be a Context instance")
371
372 self.__with_init = True
373
374 else:
375 self._bi = _no_init
376
377 def __del__(self):
378 if self.__with_init:
379 _bt_iter_destroy(self._bi)
380
381 def next(self):
382 """
383 Move trace collection position to the next event.
384 Returns 0 on success, a negative value on error.
385 """
386 return _bt_iter_next(self._bi)
387
388 def get_pos(self):
389 """Return a IterPos class of the current iterator position."""
390 ret = IterPos(0)
391 ret.__can_access = False
392 ret._pos = _bt_iter_get_pos(self._bi)
393 return ret
394
395 def set_pos(self, pos):
396 """
397 Move the iterator to a given position.
398
399 On error, the stream_heap is reinitialized and returned empty.
400 Return 0 for success.
401 Return EOF if the position requested is after the last event of the
402 trace collection.
403 Return -EINVAL when called with invalid parameter.
404 Return -ENOMEM if the stream_heap could not be properly initialized.
405 """
406 try:
407 return _bt_iter_set_pos(self._bi, pos._pos)
408 except AttributeError:
409 raise TypeError("in set_pos, "
410 "argument 2 must be a IterPos instance")
411
412 def create_time_pos(self, timestamp):
413 """
414 Create a position based on time
415 This function allocates and returns a new IterPos to be able to
416 restore an iterator position based on a timestamp.
417 """
418
419 if timestamp < 0:
420 raise TypeError("timestamp must be an unsigned int")
421
422 ret = IterPos(0)
423 ret.__can_access = False
424 ret._pos = _bt_iter_create_time_pos(self._bi, timestamp)
425 return ret
426 %}
427
428
429 /* =================================================================
430 CLOCK-TYPE.H
431 ¯¯¯¯¯¯¯¯¯¯¯¯
432 *** Enum copied from clock-type.h­
433 All changes must also be made here
434 */
435 %rename("CLOCK_CYCLES") BT_CLOCK_CYCLES;
436 %rename("CLOCK_REAL") BT_CLOCK_REAL;
437
438 enum bt_clock_type {
439 BT_CLOCK_CYCLES = 0,
440 BT_CLOCK_REAL
441 };
442
443 /* =================================================================
444 TRACE-HANDLE.H, TRACE-HANDLE-INTERNAL.H
445 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
446 */
447
448 %rename("_bt_trace_handle_create") bt_trace_handle_create(struct bt_context *ctx);
449 %rename("_bt_trace_handle_destroy") bt_trace_handle_destroy(struct bt_trace_handle *bt);
450 struct bt_trace_handle *bt_trace_handle_create(struct bt_context *ctx);
451 void bt_trace_handle_destroy(struct bt_trace_handle *bt);
452
453 %rename("_bt_trace_handle_get_path") bt_trace_handle_get_path(struct bt_context *ctx,
454 int handle_id);
455 %rename("_bt_trace_handle_get_timestamp_begin") bt_trace_handle_get_timestamp_begin(
456 struct bt_context *ctx, int handle_id, enum bt_clock_type type);
457 %rename("_bt_trace_handle_get_timestamp_end") bt_trace_handle_get_timestamp_end(
458 struct bt_context *ctx, int handle_id, enum bt_clock_type type);
459 %rename("_bt_trace_handle_get_id") bt_trace_handle_get_id(struct bt_trace_handle *th);
460 int bt_trace_handle_get_id(struct bt_trace_handle *th);
461 const char *bt_trace_handle_get_path(struct bt_context *ctx, int handle_id);
462 uint64_t bt_trace_handle_get_timestamp_begin(struct bt_context *ctx, int handle_id,
463 enum bt_clock_type type);
464 uint64_t bt_trace_handle_get_timestamp_end(struct bt_context *ctx, int handle_id,
465 enum bt_clock_type type);
466
467 %rename("_bt_ctf_event_get_handle_id") bt_ctf_event_get_handle_id(
468 const struct bt_ctf_event *event);
469 int bt_ctf_event_get_handle_id(const struct bt_ctf_event *event);
470
471
472 %pythoncode%{
473
474 class TraceHandle(object):
475 """
476 The TraceHandle allows the user to manipulate a trace file directly.
477 It is a unique identifier representing a trace file.
478 Do not instantiate.
479 """
480
481 def __init__(self):
482 raise NotImplementedError("TraceHandle cannot be instantiated")
483
484 def __repr__(self):
485 return "Babeltrace TraceHandle: trace_id('{}')".format(self._id)
486
487 def get_id(self):
488 """Return the TraceHandle id."""
489 return self._id
490
491 def get_path(self, context):
492 """Return the path of a TraceHandle."""
493 try:
494 return _bt_trace_handle_get_path(context._c, self._id)
495 except AttributeError:
496 raise TypeError("in get_path, "
497 "argument 2 must be a Context instance")
498
499 def get_timestamp_begin(self, context, clock_type):
500 """Return the creation time of the buffers of a trace."""
501 try:
502 return _bt_trace_handle_get_timestamp_begin(
503 context._c, self._id,clock_type)
504 except AttributeError:
505 raise TypeError("in get_timestamp_begin, "
506 "argument 2 must be a Context instance")
507
508 def get_timestamp_end(self, context, clock_type):
509 """Return the destruction timestamp of the buffers of a trace."""
510 try:
511 return _bt_trace_handle_get_timestamp_end(
512 context._c, self._id, clock_type)
513 except AttributeError:
514 raise TypeError("in get_timestamp_end, "
515 "argument 2 must be a Context instance")
516
517 %}
518
519
520
521 // =================================================================
522 // CTF
523 // =================================================================
524
525 /* =================================================================
526 ITERATOR.H, EVENTS.H
527 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
528 */
529
530 //Iterator
531 %rename("_bt_ctf_iter_create") bt_ctf_iter_create(struct bt_context *ctx,
532 const struct bt_iter_pos *begin_pos,
533 const struct bt_iter_pos *end_pos);
534 %rename("_bt_ctf_get_iter") bt_ctf_get_iter(struct bt_ctf_iter *iter);
535 %rename("_bt_ctf_iter_destroy") bt_ctf_iter_destroy(struct bt_ctf_iter *iter);
536 %rename("_bt_ctf_iter_read_event") bt_ctf_iter_read_event(struct bt_ctf_iter *iter);
537
538 struct bt_ctf_iter *bt_ctf_iter_create(struct bt_context *ctx,
539 const struct bt_iter_pos *begin_pos,
540 const struct bt_iter_pos *end_pos);
541 struct bt_iter *bt_ctf_get_iter(struct bt_ctf_iter *iter);
542 void bt_ctf_iter_destroy(struct bt_ctf_iter *iter);
543 struct bt_ctf_event *bt_ctf_iter_read_event(struct bt_ctf_iter *iter);
544
545
546 //Events
547
548 %rename("_bt_ctf_get_top_level_scope") bt_ctf_get_top_level_scope(const struct
549 bt_ctf_event *event, enum bt_ctf_scope scope);
550 %rename("_bt_ctf_event_name") bt_ctf_event_name(const struct bt_ctf_event *ctf_event);
551 %rename("_bt_ctf_get_timestamp") bt_ctf_get_timestamp(
552 const struct bt_ctf_event *ctf_event);
553 %rename("_bt_ctf_get_cycles") bt_ctf_get_cycles(
554 const struct bt_ctf_event *ctf_event);
555
556 %rename("_bt_ctf_get_field") bt_ctf_get_field(const struct bt_ctf_event *ctf_event,
557 const struct definition *scope, const char *field);
558 %rename("_bt_ctf_get_index") bt_ctf_get_index(const struct bt_ctf_event *ctf_event,
559 const struct definition *field, unsigned int index);
560 %rename("_bt_ctf_field_name") bt_ctf_field_name(const struct definition *def);
561 %rename("_bt_ctf_field_type") bt_ctf_field_type(const struct definition *def);
562 %rename("_bt_ctf_get_int_signedness") bt_ctf_get_int_signedness(
563 const struct definition *field);
564 %rename("_bt_ctf_get_int_base") bt_ctf_get_int_base(const struct definition *field);
565 %rename("_bt_ctf_get_int_byte_order") bt_ctf_get_int_byte_order(
566 const struct definition *field);
567 %rename("_bt_ctf_get_int_len") bt_ctf_get_int_len(const struct definition *field);
568 %rename("_bt_ctf_get_encoding") bt_ctf_get_encoding(const struct definition *field);
569 %rename("_bt_ctf_get_array_len") bt_ctf_get_array_len(const struct definition *field);
570 %rename("_bt_ctf_get_uint64") bt_ctf_get_uint64(const struct definition *field);
571 %rename("_bt_ctf_get_int64") bt_ctf_get_int64(const struct definition *field);
572 %rename("_bt_ctf_get_char_array") bt_ctf_get_char_array(const struct definition *field);
573 %rename("_bt_ctf_get_string") bt_ctf_get_string(const struct definition *field);
574 %rename("_bt_ctf_field_get_error") bt_ctf_field_get_error(void);
575 %rename("_bt_ctf_get_decl_event_name") bt_ctf_get_decl_event_name(const struct
576 bt_ctf_event_decl *event);
577 %rename("_bt_ctf_get_decl_field_name") bt_ctf_get_decl_field_name(
578 const struct bt_ctf_field_decl *field);
579
580 const struct definition *bt_ctf_get_top_level_scope(const struct bt_ctf_event *ctf_event,
581 enum bt_ctf_scope scope);
582 const char *bt_ctf_event_name(const struct bt_ctf_event *ctf_event);
583 uint64_t bt_ctf_get_timestamp(const struct bt_ctf_event *ctf_event);
584 uint64_t bt_ctf_get_cycles(const struct bt_ctf_event *ctf_event);
585 const struct definition *bt_ctf_get_field(const struct bt_ctf_event *ctf_event,
586 const struct definition *scope,
587 const char *field);
588 const struct definition *bt_ctf_get_index(const struct bt_ctf_event *ctf_event,
589 const struct definition *field,
590 unsigned int index);
591 const char *bt_ctf_field_name(const struct definition *def);
592 enum ctf_type_id bt_ctf_field_type(const struct definition *def);
593 int bt_ctf_get_int_signedness(const struct definition *field);
594 int bt_ctf_get_int_base(const struct definition *field);
595 int bt_ctf_get_int_byte_order(const struct definition *field);
596 ssize_t bt_ctf_get_int_len(const struct definition *field);
597 enum ctf_string_encoding bt_ctf_get_encoding(const struct definition *field);
598 int bt_ctf_get_array_len(const struct definition *field);
599 uint64_t bt_ctf_get_uint64(const struct definition *field);
600 int64_t bt_ctf_get_int64(const struct definition *field);
601 char *bt_ctf_get_char_array(const struct definition *field);
602 char *bt_ctf_get_string(const struct definition *field);
603 int bt_ctf_field_get_error(void);
604 const char *bt_ctf_get_decl_event_name(const struct bt_ctf_event_decl *event);
605 const char *bt_ctf_get_decl_field_name(const struct bt_ctf_field_decl *field);
606
607 %pythoncode%{
608
609 class ctf:
610
611 #enum equivalent, accessible constants
612 #These are taken directly from ctf/events.h
613 #All changes to enums must also be made here
614 class type_id:
615 UNKNOWN = 0
616 INTEGER = 1
617 FLOAT = 2
618 ENUM = 3
619 STRING = 4
620 STRUCT = 5
621 UNTAGGED_VARIANT = 6
622 VARIANT = 7
623 ARRAY = 8
624 SEQUENCE = 9
625 NR_CTF_TYPES = 10
626
627 class scope:
628 TRACE_PACKET_HEADER = 0
629 STREAM_PACKET_CONTEXT = 1
630 STREAM_EVENT_HEADER = 2
631 STREAM_EVENT_CONTEXT = 3
632 EVENT_CONTEXT = 4
633 EVENT_FIELDS = 5
634
635 class string_encoding:
636 NONE = 0
637 UTF8 = 1
638 ASCII = 2
639 UNKNOWN = 3
640
641 class Iterator(Iterator, object):
642 """
643 Allocate a CTF trace collection iterator.
644
645 begin_pos and end_pos are optional parameters to specify the
646 position at which the trace collection should be seeked upon
647 iterator creation, and the position at which iteration will
648 start returning "EOF".
649
650 By default, if begin_pos is None, a SEEK_CUR is performed at
651 creation. By default, if end_pos is None, a SEEK_END (end of
652 trace) is the EOF criterion.
653
654 Only one iterator can be created against a context. If more than one
655 iterator is being created for the same context, the second creation
656 will return None. The previous iterator must be destroyed before
657 creation of the new iterator for this function to succeed.
658 """
659
660 def __new__(cls, context, begin_pos = None, end_pos = None):
661 # __new__ is used to control the return value
662 # as the ctf.Iterator class should return None
663 # if bt_ctf_iter_create returns NULL
664
665 if begin_pos is None:
666 bp = None
667 else:
668 bp = begin_pos._pos
669 if end_pos is None:
670 ep = None
671 else:
672 ep = end_pos._pos
673 try:
674 it = _bt_ctf_iter_create(context._c, bp, ep)
675 except AttributeError:
676 raise TypeError("in __init__, "
677 "argument 2 must be a Context instance")
678 if it is None:
679 return None
680
681 ret_class = super(ctf.Iterator, cls).__new__(cls)
682 ret_class._i = it
683 return ret_class
684
685 def __init__(self, context, begin_pos = None, end_pos = None):
686 Iterator.__init__(self, None, None, None,
687 _bt_ctf_get_iter(self._i))
688
689 def __del__(self):
690 _bt_ctf_iter_destroy(self._i)
691
692 def read_event(self):
693 """
694 Read the iterator's current event data.
695 Return current event on success, None on end of trace.
696 """
697 ret = _bt_ctf_iter_read_event(self._i)
698 if ret is None:
699 return ret
700 ev = ctf.Event.__new__(ctf.Event)
701 ev._e = ret
702 return ev
703
704
705 class Event(object):
706 """
707 This class represents an event from the trace.
708 It is obtained with read_event() from ctf.Iterator.
709 Do not instantiate.
710 """
711
712 def __init__(self):
713 raise NotImplementedError("ctf.Event cannot be instantiated")
714
715 def get_top_level_scope(self, scope):
716 """
717 Return a definition of the top-level scope
718 Top-level scopes are defined in ctf.scope.
719 In order to get a field or a field list, the user needs to pass a
720 scope as argument, this scope can be a top-level scope or a scope
721 relative to an arbitrary field. This function provides the mapping
722 between the scope and the actual definition of top-level scopes.
723 On error return None.
724 """
725 evDef = ctf.Definition.__new__(ctf.Definition)
726 evDef._d = _bt_ctf_get_top_level_scope(self._e, scope)
727 if evDef._d is None:
728 return None
729 return evDef
730
731 def get_name(self):
732 """Return the name of the event or None on error."""
733 return _bt_ctf_event_name(self._e)
734
735 def get_cycles(self):
736 """
737 Return the timestamp of the event as written in
738 the packet (in cycles) or -1ULL on error.
739 """
740 return _bt_ctf_get_cycles(self._e)
741
742 def get_timestamp(self):
743 """
744 Return the timestamp of the event offsetted with the
745 system clock source or -1ULL on error.
746 """
747 return _bt_ctf_get_timestamp(self._e)
748
749 def get_field(self, scope, field):
750 """Return the definition of a specific field."""
751 evDef = ctf.Definition.__new__(ctf.Definition)
752 try:
753 evDef._d = _bt_ctf_get_field(self._e, scope._d, field)
754 except AttributeError:
755 raise TypeError("in get_field, argument 2 must be a "
756 "Definition (scope) instance")
757 return evDef
758
759 def get_field_list(self, scope):
760 """
761 Return a list of Definitions
762 Return None on error.
763 """
764 try:
765 field_lc = _bt_python_field_listcaller(self._e, scope._d)
766 except AttributeError:
767 raise TypeError("in get_field_list, argument 2 must be a "
768 "Definition (scope) instance")
769
770 if field_lc is None:
771 return None
772
773 def_list = []
774 i = 0
775 while True:
776 tmp = ctf.Definition.__new__(ctf.Definition)
777 tmp._d = _bt_python_field_one_from_list(field_lc, i)
778
779 if tmp._d is None:
780 #Last item of list is None, assured in
781 #_bt_python_field_listcaller
782 break
783
784 def_list.append(tmp)
785 i += 1
786 return def_list
787
788 def get_index(self, field, index):
789 """
790 If the field is an array or a sequence, return the element
791 at position index, otherwise return None
792 """
793 evDef = ctf.Definition.__new__(ctf.Definition)
794 try:
795 evDef._d = _bt_ctf_get_index(self._e, field._d, index)
796 except AttributeError:
797 raise TypeError("in get_index, argument 2 must be a "
798 "Definition (field) instance")
799
800 if evDef._d is None:
801 return None
802 return evDef
803
804 def get_handle(self):
805 """
806 Get the TraceHandle associated with an event
807 Return None on error
808 """
809 ret = _bt_ctf_event_get_handle_id(self._e)
810 if ret < 0:
811 return None
812
813 th = TraceHandle.__new__(TraceHandle)
814 th._id = ret
815 return th
816
817 def get_context(self):
818 """
819 Get the context associated with an event.
820 Return None on error.
821 """
822 ctx = Context()
823 ctx._c = _bt_ctf_event_get_context(self._e);
824 if ctx._c is None:
825 return None
826 else:
827 return ctx
828
829
830 class Definition(object):
831 """Definition class. Do not instantiate."""
832
833 def __init__(self):
834 raise NotImplementedError("ctf.Definition cannot be instantiated")
835
836 def __repr__(self):
837 return "Babeltrace Definition: name('{}'), type({})".format(
838 self.field_name(), self.field_type())
839
840 def field_name(self):
841 """Return the name of a field or None on error."""
842 return _bt_ctf_field_name(self._d)
843
844 def field_type(self):
845 """Return the type of a field or -1 if unknown."""
846 return _bt_ctf_field_type(self._d)
847
848 def get_int_signedness(self):
849 """
850 Return the signedness of an integer:
851 0 if unsigned; 1 if signed; -1 on error.
852 """
853 return _bt_ctf_get_int_signedness(self._d)
854
855 def get_int_base(self):
856 """Return the base of an int or a negative value on error."""
857 return _bt_ctf_get_int_base(self._d)
858
859 def get_int_byte_order(self):
860 """
861 Return the byte order of an int or a negative
862 value on error.
863 """
864 return _bt_ctf_get_int_byte_order(self._d)
865
866 def get_int_len(self):
867 """
868 Return the size, in bits, of an int or a negative
869 value on error.
870 """
871 return _bt_ctf_get_int_len(self._d)
872
873 def get_encoding(self):
874 """
875 Return the encoding of an int or a string.
876 Return a negative value on error.
877 """
878 return _bt_ctf_get_encoding(self._d)
879
880 def get_array_len(self):
881 """
882 Return the len of an array or a negative
883 value on error.
884 """
885 return _bt_ctf_get_array_len(self._d)
886
887 def get_uint64(self):
888 """
889 Return the value associated with the field.
890 If the field does not exist or is not of the type requested,
891 the value returned is undefined. To check if an error occured,
892 use the ctf.field_error() function after accessing a field.
893 """
894 return _bt_ctf_get_uint64(self._d)
895
896 def get_int64(self):
897 """
898 Return the value associated with the field.
899 If the field does not exist or is not of the type requested,
900 the value returned is undefined. To check if an error occured,
901 use the ctf.field_error() function after accessing a field.
902 """
903 return _bt_ctf_get_int64(self._d)
904
905 def get_char_array(self):
906 """
907 Return the value associated with the field.
908 If the field does not exist or is not of the type requested,
909 the value returned is undefined. To check if an error occured,
910 use the ctf.field_error() function after accessing a field.
911 """
912 return _bt_ctf_get_char_array(self._d)
913
914 def get_str(self):
915 """
916 Return the value associated with the field.
917 If the field does not exist or is not of the type requested,
918 the value returned is undefined. To check if an error occured,
919 use the ctf.field_error() function after accessing a field.
920 """
921 return _bt_ctf_get_string(self._d)
922
923
924 class EventDecl(object):
925 """Event declaration class. Do not instantiate."""
926
927 def __init__(self):
928 raise NotImplementedError("ctf.EventDecl cannot be instantiated")
929
930 def __repr__(self):
931 return "Babeltrace EventDecl: name {}".format(self.get_name())
932
933 def get_name(self):
934 """Return the name of the event or None on error"""
935 return _bt_ctf_get_decl_event_name(self._d)
936
937 def get_decl_fields(self, scope):
938 """
939 Return a list of ctf.FieldDecl
940 Return None on error.
941 """
942 ptr_list = _by_python_field_decl_listcaller(self._d, scope)
943
944 if ptr_list is None:
945 return None
946
947 decl_list = []
948 i = 0
949 while True:
950 tmp = ctf.FieldDecl.__new__(ctf.FieldDecl)
951 tmp._d = _bt_python_field_decl_one_from_list(
952 ptr_list, i)
953
954 if tmp._d is None:
955 #Last item of list is None
956 break
957
958 decl_list.append(tmp)
959 i += 1
960 return decl_list
961
962
963 class FieldDecl(object):
964 """Field declaration class. Do not instantiate."""
965
966 def __init__(self):
967 raise NotImplementedError("ctf.FieldDecl cannot be instantiated")
968
969 def __repr__(self):
970 return "Babeltrace FieldDecl: name {}".format(self.get_name())
971
972 def get_name(self):
973 """Return the name of a FieldDecl or None on error"""
974 return _bt_ctf_get_decl_field_name(self._d)
975
976
977 @staticmethod
978 def field_error():
979 """
980 Return the last error code encountered while
981 accessing a field and reset the error flag.
982 Return 0 if no error, a negative value otherwise.
983 """
984 return _bt_ctf_field_get_error()
985
986 @staticmethod
987 def get_event_decl_list(trace_handle, context):
988 """
989 Return a list of ctf.EventDecl
990 Return None on error.
991 """
992 try:
993 handle_id = trace_handle._id
994 except AttributeError:
995 raise TypeError("in get_event_decl_list, "
996 "argument 1 must be a TraceHandle instance")
997 try:
998 ptr_list = _bt_python_event_decl_listcaller(handle_id, context._c)
999 except AttributeError:
1000 raise TypeError("in get_event_decl_list, "
1001 "argument 2 must be a Context instance")
1002
1003 if ptr_list is None:
1004 return None
1005
1006 decl_list = []
1007 i = 0
1008 while True:
1009 tmp = ctf.EventDecl.__new__(ctf.EventDecl)
1010 tmp._d = _bt_python_decl_one_from_list(ptr_list, i)
1011
1012 if tmp._d is None:
1013 #Last item of list is None
1014 break
1015
1016 decl_list.append(tmp)
1017 i += 1
1018 return decl_list
1019
1020 %}
1021
1022
1023
1024 // =================================================================
1025 // NEW FUNCTIONS
1026 // File and list-related
1027 // python-complements.h
1028 // =================================================================
1029
1030 %include python-complements.c
1031
1032 %pythoncode %{
1033
1034 class File(object):
1035 """
1036 Open a file for babeltrace.
1037
1038 file_path is a string containing the path or None to use the
1039 standard output in writing mode.
1040
1041 The mode can be 'r', 'w' or 'a' for reading (default), writing or
1042 appending. The file will be created if it doesn't exist when
1043 opened for writing or appending; it will be truncated when opened
1044 for writing. Add a 'b' to the mode for binary files. Add a '+'
1045 to the mode to allow simultaneous reading and writing.
1046 """
1047
1048 def __new__(cls, file_path, mode='r'):
1049 # __new__ is used to control the return value
1050 # as the File class should return None
1051 # if _bt_file_open returns NULL
1052
1053 # Type check
1054 if file_path is not None and type(file_path) is not str:
1055 raise TypeError("in method __init__, argument 2 of type 'str'")
1056 if type(mode) is not str:
1057 raise TypeError("in method __init__, argument 3 of type 'str'")
1058
1059 # Opening file
1060 file_ptr = _bt_file_open(file_path, mode)
1061 if file_ptr is None:
1062 return None
1063
1064 # Class instantiation
1065 file_inst = super(File, cls).__new__(cls)
1066 file_inst._file = file_ptr
1067 return file_inst
1068
1069 def __init__(self, file_path, mode='r'):
1070 self._opened = True
1071 self._use_stdout = False
1072
1073 if file_path is None:
1074 # use stdout
1075 file_path = "stdout"
1076 mode = 'w'
1077 self._use_stdout = True
1078
1079 self._file_path = file_path
1080 self._mode = mode
1081
1082 def __del__(self):
1083 self.close()
1084
1085 def __repr__(self):
1086 if self._opened:
1087 stat = 'opened'
1088 else:
1089 stat = 'closed'
1090 return "{} babeltrace File; file_path('{}'), mode('{}')".format(
1091 stat, self._file_path, self._mode)
1092
1093 def close(self):
1094 """Close the file. Is also called using del."""
1095 if self._opened and not self._use_stdout:
1096 _bt_file_close(self._file)
1097 self._opened = False
1098 %}
This page took 0.051352 seconds and 4 git commands to generate.