4 * Babeltrace Python Module interface file
6 * Copyright 2012 EfficiOS Inc.
8 * Author: Danny Serres <danny.serres@efficios.com>
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:
17 * The above copyright notice and this permission notice shall be included in
18 * all copies or substantial portions of the Software.
23 "BABELTRACE_VERSION_STR
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.
29 To use this module, the first step is to create a Context and add a
33 %module(docstring=DOCSTRING) babeltrace
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/types.h>
49 #include <babeltrace/ctf/iterator.h>
50 #include "python-complements.h"
53 typedef unsigned long long uint64_t;
54 typedef long long int64_t;
55 typedef int bt_intern_str;
57 /* =================================================================
59 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
62 FILE *_bt_file_open(char *file_path, char *mode);
63 void _bt_file_close(FILE *fp);
64 struct bt_definition **_bt_python_field_listcaller(
65 const struct bt_ctf_event *ctf_event,
66 const struct bt_definition *scope,
67 unsigned int *OUTPUT);
68 struct bt_definition *_bt_python_field_one_from_list(
69 struct bt_definition **list, int index);
70 struct bt_ctf_event_decl **_bt_python_event_decl_listcaller(
72 struct bt_context *ctx,
73 unsigned int *OUTPUT);
74 struct bt_ctf_event_decl *_bt_python_decl_one_from_list(
75 struct bt_ctf_event_decl **list, int index);
76 struct bt_ctf_field_decl **_by_python_field_decl_listcaller(
77 struct bt_ctf_event_decl *event_decl,
78 enum bt_ctf_scope scope,
79 unsigned int *OUTPUT);
80 struct bt_ctf_field_decl *_bt_python_field_decl_one_from_list(
81 struct bt_ctf_field_decl **list, int index);
82 struct definition_array *_bt_python_get_array_from_def(
83 struct bt_definition *field);
84 struct definition_sequence *_bt_python_get_sequence_from_def(
85 struct bt_definition *field);
87 /* =================================================================
88 CONTEXT.H, CONTEXT-INTERNAL.H
89 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
92 %rename("_bt_context_create") bt_context_create(void);
93 %rename("_bt_context_add_trace") bt_context_add_trace(
94 struct bt_context *ctx, const char *path, const char *format,
95 void (*packet_seek)(struct bt_stream_pos *pos, size_t index, int whence),
96 struct bt_mmap_stream_list *stream_list, FILE *metadata);
97 %rename("_bt_context_remove_trace") bt_context_remove_trace(
98 struct bt_context *ctx, int trace_id);
99 %rename("_bt_context_get") bt_context_get(struct bt_context *ctx);
100 %rename("_bt_context_put") bt_context_put(struct bt_context *ctx);
101 %rename("_bt_ctf_event_get_context") bt_ctf_event_get_context(
102 const struct bt_ctf_event *event);
104 struct bt_context *bt_context_create(void);
105 int bt_context_add_trace(struct bt_context *ctx, const char *path, const char *format,
106 void (*packet_seek)(struct bt_stream_pos *pos, size_t index, int whence),
107 struct bt_mmap_stream_list *stream_list, FILE *metadata);
108 void bt_context_remove_trace(struct bt_context *ctx, int trace_id);
109 void bt_context_get(struct bt_context *ctx);
110 void bt_context_put(struct bt_context *ctx);
111 struct bt_context *bt_ctf_event_get_context(const struct bt_ctf_event *event);
113 // class Context to prevent direct access to struct bt_context
117 The context represents the object in which a trace_collection is
118 open. As long as this structure is allocated, the trace_collection
119 is open and the traces it contains can be read and seeked by the
120 iterators and callbacks.
124 self._c = _bt_context_create()
127 _bt_context_put(self._c)
129 def add_trace(self, path, format_str,
130 packet_seek=None, stream_list=None, metadata=None):
132 Add a trace by path to the context.
136 path is the path to the trace, it is not recursive.
137 If "path" is None, stream_list is used instead as a list
138 of mmap streams to open for the trace.
140 format is a string containing the format name in which the trace was
143 packet_seek is not implemented for Python. Should be left None to
144 use the default packet_seek handler provided by the trace format.
146 stream_list is a linked list of streams, it is used to open a trace
147 where the trace data is located in memory mapped areas instead of
148 trace files, this argument should be None when path is not None.
150 The metadata parameter acts as a metadata override when not None,
151 otherwise the format handles the metadata opening.
153 Return: the corresponding TraceHandle on success or None on error.
155 if metadata is not None:
156 metadata = metadata._file
158 ret = _bt_context_add_trace(self._c, path, format_str, packet_seek,
159 stream_list, metadata)
163 th = TraceHandle.__new__(TraceHandle)
167 def add_traces_recursive(self, path, format_str):
169 Open a trace recursively.
171 Find each trace present in the subdirectory starting from the given
172 path, and add them to the context.
174 Return a dict of TraceHandle instances (the full path is the key).
175 Return None on error.
185 for fullpath, dirs, files in os.walk(path):
186 if "metadata" in files:
187 trace_handle = self.add_trace(fullpath, format_str)
188 if trace_handle is None:
192 trace_handles[fullpath] = trace_handle
195 if noTrace and error:
199 def remove_trace(self, trace_handle):
201 Remove a trace from the context.
202 Effectively closing the trace.
205 _bt_context_remove_trace(self._c, trace_handle._id)
206 except AttributeError:
207 raise TypeError("in remove_trace, "
208 "argument 2 must be a TraceHandle instance")
213 /* =================================================================
218 %rename("lookup_format") bt_lookup_format(bt_intern_str qname);
219 %rename("_bt_print_format_list") bt_fprintf_format_list(FILE *fp);
220 %rename("register_format") bt_register_format(struct format *format);
221 %rename("unregister_format") bt_unregister_format(struct bt_format *format);
223 extern struct format *bt_lookup_format(bt_intern_str qname);
224 extern void bt_fprintf_format_list(FILE *fp);
225 extern int bt_register_format(struct bt_format *format);
226 extern void bt_unregister_format(struct bt_format *format);
230 def print_format_list(babeltrace_file):
232 Print a list of available formats to file.
234 babeltrace_file must be a File instance opened in write mode.
237 if babeltrace_file._file is not None:
238 _bt_print_format_list(babeltrace_file._file)
239 except AttributeError:
240 raise TypeError("in print_format_list, "
241 "argument 1 must be a File instance")
246 /* =================================================================
247 ITERATOR.H, ITERATOR-INTERNAL.H
248 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
251 %rename("_bt_iter_create") bt_iter_create(struct bt_context *ctx,
252 const struct bt_iter_pos *begin_pos, const struct bt_iter_pos *end_pos);
253 %rename("_bt_iter_destroy") bt_iter_destroy(struct bt_iter *iter);
254 %rename("_bt_iter_next") bt_iter_next(struct bt_iter *iter);
255 %rename("_bt_iter_get_pos") bt_iter_get_pos(struct bt_iter *iter);
256 %rename("_bt_iter_free_pos") bt_iter_free_pos(struct bt_iter_pos *pos);
257 %rename("_bt_iter_set_pos") bt_iter_set_pos(struct bt_iter *iter,
258 const struct bt_iter_pos *pos);
259 %rename("_bt_iter_create_time_pos") bt_iter_create_time_pos(struct bt_iter *iter,
262 struct bt_iter *bt_iter_create(struct bt_context *ctx,
263 const struct bt_iter_pos *begin_pos, const struct bt_iter_pos *end_pos);
264 void bt_iter_destroy(struct bt_iter *iter);
265 int bt_iter_next(struct bt_iter *iter);
266 struct bt_iter_pos *bt_iter_get_pos(struct bt_iter *iter);
267 void bt_iter_free_pos(struct bt_iter_pos *pos);
268 int bt_iter_set_pos(struct bt_iter *iter, const struct bt_iter_pos *pos);
269 struct bt_iter_pos *bt_iter_create_time_pos(struct bt_iter *iter, uint64_t timestamp);
271 %rename("_bt_iter_pos") bt_iter_pos;
272 %rename("SEEK_TIME") BT_SEEK_TIME;
273 %rename("SEEK_RESTORE") BT_SEEK_RESTORE;
274 %rename("SEEK_CUR") BT_SEEK_CUR;
275 %rename("SEEK_BEGIN") BT_SEEK_BEGIN;
276 %rename("SEEK_LAST") BT_SEEK_LAST;
278 // This struct is taken from iterator.h
279 // All changes to the struct must also be made here
282 BT_SEEK_TIME, /* uses u.seek_time */
283 BT_SEEK_RESTORE, /* uses u.restore */
290 struct bt_saved_pos *restore;
298 """This class represents the position where to set an iterator."""
302 def __init__(self, seek_type, seek_time = None):
304 seek_type represents the type of seek to use.
305 seek_time is the timestamp to seek to when using SEEK_TIME, it
306 is expressed in nanoseconds
307 Only use SEEK_RESTORE on IterPos obtained from the get_pos function
311 self._pos = _bt_iter_pos()
312 self._pos.type = seek_type
313 if seek_time and seek_type == SEEK_TIME:
314 self._pos.u.seek_time = seek_time
315 self.__can_access = True
318 if not self.__can_access:
319 _bt_iter_free_pos(self._pos)
323 raise AttributeError("seek_type is not available")
324 return self._pos.type
326 def _set_type(self, seek_type):
328 raise AttributeError("seek_type is not available")
329 self._pos.type = seek_type
333 raise AttributeError("seek_time is not available")
335 elif self._pos.type is not SEEK_TIME:
336 raise TypeError("seek_type is not SEEK_TIME")
338 return self._pos.u.seek_time
340 def _set_time(self, time):
342 raise AttributeError("seek_time is not available")
344 elif self._pos.type is not SEEK_TIME:
345 raise TypeError("seek_type is not SEEK_TIME")
347 self._pos.u.seek_time = time
353 seek_type = property(_get_type, _set_type)
354 seek_time = property(_get_time, _set_time)
361 def __init__(self, context, begin_pos = None, end_pos = None, _no_init = None):
363 Allocate a trace collection iterator.
365 begin_pos and end_pos are optional parameters to specify the
366 position at which the trace collection should be seeked upon
367 iterator creation, and the position at which iteration will
368 start returning "EOF".
370 By default, if begin_pos is None, a BT_SEEK_CUR is performed at
371 creation. By default, if end_pos is None, a BT_SEEK_END (end of
372 trace) is the EOF criterion.
375 if begin_pos is None:
380 except AttributeError:
381 raise TypeError("in __init__, "
382 "argument 3 must be a IterPos instance")
389 except AttributeError:
390 raise TypeError("in __init__, "
391 "argument 4 must be a IterPos instance")
394 self._bi = _bt_iter_create(context._c, bp, ep)
395 except AttributeError:
396 raise TypeError("in __init__, "
397 "argument 2 must be a Context instance")
399 self.__with_init = True
406 _bt_iter_destroy(self._bi)
410 Move trace collection position to the next event.
411 Returns 0 on success, a negative value on error.
413 return _bt_iter_next(self._bi)
416 """Return a IterPos class of the current iterator position."""
418 ret.__can_access = False
419 ret._pos = _bt_iter_get_pos(self._bi)
422 def set_pos(self, pos):
424 Move the iterator to a given position.
426 On error, the stream_heap is reinitialized and returned empty.
427 Return 0 for success.
428 Return EOF if the position requested is after the last event of the
430 Return -EINVAL when called with invalid parameter.
431 Return -ENOMEM if the stream_heap could not be properly initialized.
434 return _bt_iter_set_pos(self._bi, pos._pos)
435 except AttributeError:
436 raise TypeError("in set_pos, "
437 "argument 2 must be a IterPos instance")
439 def create_time_pos(self, timestamp):
441 Create a position based on time
442 This function allocates and returns a new IterPos to be able to
443 restore an iterator position based on a timestamp.
447 raise TypeError("timestamp must be an unsigned int")
450 ret.__can_access = False
451 ret._pos = _bt_iter_create_time_pos(self._bi, timestamp)
456 /* =================================================================
459 *** Enum copied from clock-type.h
460 All changes must also be made here
462 %rename("CLOCK_CYCLES") BT_CLOCK_CYCLES;
463 %rename("CLOCK_REAL") BT_CLOCK_REAL;
470 /* =================================================================
471 TRACE-HANDLE.H, TRACE-HANDLE-INTERNAL.H
472 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
475 %rename("_bt_trace_handle_create") bt_trace_handle_create(struct bt_context *ctx);
476 %rename("_bt_trace_handle_destroy") bt_trace_handle_destroy(struct bt_trace_handle *bt);
477 struct bt_trace_handle *bt_trace_handle_create(struct bt_context *ctx);
478 void bt_trace_handle_destroy(struct bt_trace_handle *bt);
480 %rename("_bt_trace_handle_get_path") bt_trace_handle_get_path(struct bt_context *ctx,
482 %rename("_bt_trace_handle_get_timestamp_begin") bt_trace_handle_get_timestamp_begin(
483 struct bt_context *ctx, int handle_id, enum bt_clock_type type);
484 %rename("_bt_trace_handle_get_timestamp_end") bt_trace_handle_get_timestamp_end(
485 struct bt_context *ctx, int handle_id, enum bt_clock_type type);
486 const char *bt_trace_handle_get_path(struct bt_context *ctx, int handle_id);
487 uint64_t bt_trace_handle_get_timestamp_begin(struct bt_context *ctx, int handle_id,
488 enum bt_clock_type type);
489 uint64_t bt_trace_handle_get_timestamp_end(struct bt_context *ctx, int handle_id,
490 enum bt_clock_type type);
492 %rename("_bt_ctf_event_get_handle_id") bt_ctf_event_get_handle_id(
493 const struct bt_ctf_event *event);
494 int bt_ctf_event_get_handle_id(const struct bt_ctf_event *event);
499 class TraceHandle(object):
501 The TraceHandle allows the user to manipulate a trace file directly.
502 It is a unique identifier representing a trace file.
507 raise NotImplementedError("TraceHandle cannot be instantiated")
510 return "Babeltrace TraceHandle: trace_id('{0}')".format(self._id)
513 """Return the TraceHandle id."""
516 def get_path(self, context):
517 """Return the path of a TraceHandle."""
519 return _bt_trace_handle_get_path(context._c, self._id)
520 except AttributeError:
521 raise TypeError("in get_path, "
522 "argument 2 must be a Context instance")
524 def get_timestamp_begin(self, context, clock_type):
525 """Return the creation time of the buffers of a trace."""
527 return _bt_trace_handle_get_timestamp_begin(
528 context._c, self._id,clock_type)
529 except AttributeError:
530 raise TypeError("in get_timestamp_begin, "
531 "argument 2 must be a Context instance")
533 def get_timestamp_end(self, context, clock_type):
534 """Return the destruction timestamp of the buffers of a trace."""
536 return _bt_trace_handle_get_timestamp_end(
537 context._c, self._id, clock_type)
538 except AttributeError:
539 raise TypeError("in get_timestamp_end, "
540 "argument 2 must be a Context instance")
546 // =================================================================
548 // =================================================================
550 /* =================================================================
556 %rename("_bt_ctf_iter_create") bt_ctf_iter_create(struct bt_context *ctx,
557 const struct bt_iter_pos *begin_pos,
558 const struct bt_iter_pos *end_pos);
559 %rename("_bt_ctf_get_iter") bt_ctf_get_iter(struct bt_ctf_iter *iter);
560 %rename("_bt_ctf_iter_destroy") bt_ctf_iter_destroy(struct bt_ctf_iter *iter);
561 %rename("_bt_ctf_iter_read_event") bt_ctf_iter_read_event(struct bt_ctf_iter *iter);
563 struct bt_ctf_iter *bt_ctf_iter_create(struct bt_context *ctx,
564 const struct bt_iter_pos *begin_pos,
565 const struct bt_iter_pos *end_pos);
566 struct bt_iter *bt_ctf_get_iter(struct bt_ctf_iter *iter);
567 void bt_ctf_iter_destroy(struct bt_ctf_iter *iter);
568 struct bt_ctf_event *bt_ctf_iter_read_event(struct bt_ctf_iter *iter);
573 %rename("_bt_ctf_get_top_level_scope") bt_ctf_get_top_level_scope(const struct
574 bt_ctf_event *event, enum bt_ctf_scope scope);
575 %rename("_bt_ctf_event_name") bt_ctf_event_name(const struct bt_ctf_event *ctf_event);
576 %rename("_bt_ctf_get_timestamp") bt_ctf_get_timestamp(
577 const struct bt_ctf_event *ctf_event);
578 %rename("_bt_ctf_get_cycles") bt_ctf_get_cycles(
579 const struct bt_ctf_event *ctf_event);
581 %rename("_bt_ctf_get_field") bt_ctf_get_field(const struct bt_ctf_event *ctf_event,
582 const struct bt_definition *scope, const char *field);
583 %rename("_bt_ctf_get_index") bt_ctf_get_index(const struct bt_ctf_event *ctf_event,
584 const struct bt_definition *field, unsigned int index);
585 %rename("_bt_ctf_field_name") bt_ctf_field_name(const struct bt_definition *field);
586 %rename("_bt_ctf_field_type") bt_ctf_field_type(const struct bt_declaration *field);
587 %rename("_bt_ctf_get_int_signedness") bt_ctf_get_int_signedness(
588 const struct bt_declaration *field);
589 %rename("_bt_ctf_get_int_base") bt_ctf_get_int_base(const struct bt_declaration *field);
590 %rename("_bt_ctf_get_int_byte_order") bt_ctf_get_int_byte_order(
591 const struct bt_declaration *field);
592 %rename("_bt_ctf_get_int_len") bt_ctf_get_int_len(const struct bt_declaration *field);
593 %rename("_bt_ctf_get_enum_int") bt_ctf_get_enum_int(const struct bt_definition *field);
594 %rename("_bt_ctf_get_enum_str") bt_ctf_get_enum_str(const struct bt_definition *field);
595 %rename("_bt_ctf_get_encoding") bt_ctf_get_encoding(const struct bt_declaration *field);
596 %rename("_bt_ctf_get_array_len") bt_ctf_get_array_len(const struct bt_declaration *field);
597 %rename("_bt_ctf_get_uint64") bt_ctf_get_uint64(const struct bt_definition *field);
598 %rename("_bt_ctf_get_int64") bt_ctf_get_int64(const struct bt_definition *field);
599 %rename("_bt_ctf_get_char_array") bt_ctf_get_char_array(const struct bt_definition *field);
600 %rename("_bt_ctf_get_string") bt_ctf_get_string(const struct bt_definition *field);
601 %rename("_bt_ctf_get_float") bt_ctf_get_float(const struct bt_definition *field);
602 %rename("_bt_ctf_get_variant") bt_ctf_get_variant(const struct bt_definition *field);
603 %rename("_bt_ctf_field_get_error") bt_ctf_field_get_error(void);
604 %rename("_bt_ctf_get_decl_event_name") bt_ctf_get_decl_event_name(const struct
605 bt_ctf_event_decl *event);
606 %rename("_bt_ctf_get_decl_field_name") bt_ctf_get_decl_field_name(
607 const struct bt_ctf_field_decl *field);
608 %rename("_bt_ctf_get_decl_from_def") bt_ctf_get_decl_from_def(
609 const struct bt_definition *field);
610 %rename("_bt_array_index") bt_array_index(struct definition_array *array, uint64_t i);
611 %rename("_bt_sequence_len") bt_sequence_len(struct definition_sequence *sequence);
612 %rename("_bt_sequence_index") bt_sequence_index(struct definition_sequence *sequence, uint64_t i);
613 %rename("_bt_ctf_get_struct_field_count") bt_ctf_get_struct_field_count(const struct bt_definition *structure);
614 %rename("_bt_ctf_get_struct_field_index") bt_ctf_get_struct_field_index(const struct bt_definition *structure, uint64_t i);
616 const struct bt_definition *bt_ctf_get_top_level_scope(const struct bt_ctf_event *ctf_event,
617 enum bt_ctf_scope scope);
618 const char *bt_ctf_event_name(const struct bt_ctf_event *ctf_event);
619 uint64_t bt_ctf_get_timestamp(const struct bt_ctf_event *ctf_event);
620 uint64_t bt_ctf_get_cycles(const struct bt_ctf_event *ctf_event);
621 const struct bt_definition *bt_ctf_get_field(const struct bt_ctf_event *ctf_event,
622 const struct bt_definition *scope,
624 const struct bt_definition *bt_ctf_get_index(const struct bt_ctf_event *ctf_event,
625 const struct bt_definition *field,
627 const char *bt_ctf_field_name(const struct bt_definition *field);
628 enum ctf_type_id bt_ctf_field_type(const struct bt_declaration *field);
629 int bt_ctf_get_int_signedness(const struct bt_declaration *field);
630 int bt_ctf_get_int_base(const struct bt_declaration *field);
631 int bt_ctf_get_int_byte_order(const struct bt_declaration *field);
632 ssize_t bt_ctf_get_int_len(const struct bt_declaration *field);
633 const struct bt_definition *bt_ctf_get_enum_int(const struct bt_definition *field);
634 const char *bt_ctf_get_enum_str(const struct bt_definition *field);
635 enum ctf_string_encoding bt_ctf_get_encoding(const struct bt_declaration *field);
636 int bt_ctf_get_array_len(const struct bt_declaration *field);
637 struct bt_definition *bt_array_index(struct definition_array *array, uint64_t i);
638 uint64_t bt_ctf_get_uint64(const struct bt_definition *field);
639 int64_t bt_ctf_get_int64(const struct bt_definition *field);
640 char *bt_ctf_get_char_array(const struct bt_definition *field);
641 char *bt_ctf_get_string(const struct bt_definition *field);
642 double bt_ctf_get_float(const struct bt_definition *field);
643 const struct bt_definition *bt_ctf_get_variant(const struct bt_definition *field);
644 int bt_ctf_field_get_error(void);
645 const char *bt_ctf_get_decl_event_name(const struct bt_ctf_event_decl *event);
646 const char *bt_ctf_get_decl_field_name(const struct bt_ctf_field_decl *field);
647 const struct bt_declaration *bt_ctf_get_decl_from_def(const struct bt_definition *field);
648 uint64_t bt_sequence_len(struct definition_sequence *sequence);
649 struct bt_definition *bt_sequence_index(struct definition_sequence *sequence, uint64_t i);
650 uint64_t bt_ctf_get_struct_field_count(const struct bt_definition *structure);
651 const struct bt_definition *bt_ctf_get_struct_field_index(const struct bt_definition *structure, uint64_t i);
657 #enum equivalent, accessible constants
658 #These are taken directly from ctf/events.h
659 #All changes to enums must also be made here
673 def get_type_id_name(id):
675 constants = [attr for attr in dir(ctf.type_id) if not callable(getattr(ctf.type_id, attr)) and not attr.startswith("__")]
676 for attr in constants:
677 if getattr(ctf.type_id, attr) == id:
683 TRACE_PACKET_HEADER = 0
684 STREAM_PACKET_CONTEXT = 1
685 STREAM_EVENT_HEADER = 2
686 STREAM_EVENT_CONTEXT = 3
690 class string_encoding:
696 class Iterator(Iterator, object):
698 Allocate a CTF trace collection iterator.
700 begin_pos and end_pos are optional parameters to specify the
701 position at which the trace collection should be seeked upon
702 iterator creation, and the position at which iteration will
703 start returning "EOF".
705 By default, if begin_pos is None, a SEEK_CUR is performed at
706 creation. By default, if end_pos is None, a SEEK_END (end of
707 trace) is the EOF criterion.
709 Only one iterator can be created against a context. If more than one
710 iterator is being created for the same context, the second creation
711 will return None. The previous iterator must be destroyed before
712 creation of the new iterator for this function to succeed.
715 def __new__(cls, context, begin_pos = None, end_pos = None):
716 # __new__ is used to control the return value
717 # as the ctf.Iterator class should return None
718 # if bt_ctf_iter_create returns NULL
720 if begin_pos is None:
729 it = _bt_ctf_iter_create(context._c, bp, ep)
730 except AttributeError:
731 raise TypeError("in __init__, "
732 "argument 2 must be a Context instance")
736 ret_class = super(ctf.Iterator, cls).__new__(cls)
740 def __init__(self, context, begin_pos = None, end_pos = None):
741 Iterator.__init__(self, None, None, None,
742 _bt_ctf_get_iter(self._i))
745 _bt_ctf_iter_destroy(self._i)
747 def read_event(self):
749 Read the iterator's current event data.
750 Return current event on success, None on end of trace.
752 ret = _bt_ctf_iter_read_event(self._i)
755 ev = ctf.Event.__new__(ctf.Event)
762 This class represents an event from the trace.
763 It is obtained with read_event() from ctf.Iterator.
768 raise NotImplementedError("ctf.Event cannot be instantiated")
770 def get_top_level_scope(self, scope):
772 Return a definition of the top-level scope
773 Top-level scopes are defined in ctf.scope.
774 In order to get a field or a field list, the user needs to pass a
775 scope as argument, this scope can be a top-level scope or a scope
776 relative to an arbitrary field. This function provides the mapping
777 between the scope and the actual definition of top-level scopes.
778 On error return None.
780 evDef = ctf.Definition.__new__(ctf.Definition)
781 evDef._d = _bt_ctf_get_top_level_scope(self._e, scope)
787 """Return the name of the event or None on error."""
788 return _bt_ctf_event_name(self._e)
790 def get_cycles(self):
792 Return the timestamp of the event as written in
793 the packet (in cycles) or -1ULL on error.
795 return _bt_ctf_get_cycles(self._e)
797 def get_timestamp(self):
799 Return the timestamp of the event offsetted with the
800 system clock source or -1ULL on error.
802 return _bt_ctf_get_timestamp(self._e)
804 def get_field_with_scope(self, scope, field):
806 Return the definition of a specific field.
807 Return None on error.
809 evDef = ctf.Definition.__new__(ctf.Definition)
811 evDef._d = _bt_ctf_get_field(self._e, scope._d, field)
812 except AttributeError:
813 raise TypeError("in get_field, argument 2 must be a "
814 "Definition (scope) instance")
820 def get_field(self, field):
822 Return the definition of fields by a name
825 eventScope = self.get_top_level_scope(ctf.scope.EVENT_FIELDS)
826 streamScope = self.get_top_level_scope(ctf.scope.STREAM_EVENT_CONTEXT)
829 if eventScope is not None:
830 evDef = self.get_field_with_scope(eventScope, field)
831 if evDef is not None:
832 fields_by_name.append(evDef)
834 if streamScope is not None:
835 evDef = self.get_field_with_scope(streamScope, field)
836 if evDef is not None:
837 fields_by_name.append(evDef);
839 if not fields_by_name:
841 return fields_by_name
843 def get_field_list_with_scope(self, scope):
845 Return a list of Definitions associated with the scope
846 Return None on error.
849 field_lc, count = _bt_python_field_listcaller(self._e, scope._d)
850 except AttributeError:
851 raise TypeError("in get_field_list, argument 2 must be a "
852 "Definition (scope) instance")
858 for i in range(count):
859 tmp = ctf.Definition.__new__(ctf.Definition)
860 tmp._d = _bt_python_field_one_from_list(field_lc, i)
866 def get_field_list(self):
867 """Return a list of Definitions or None on error."""
868 eventScope = self.get_top_level_scope(ctf.scope.EVENT_FIELDS)
869 streamScope = self.get_top_level_scope(ctf.scope.STREAM_EVENT_CONTEXT)
872 if eventScope is not None:
873 event_field_list = self.get_field_list_with_scope(eventScope)
874 if event_field_list is not None:
875 def_list = event_field_list
877 if streamScope is not None:
878 event_field_list = self.get_field_list_with_scope(streamScope)
879 if event_field_list is not None:
880 def_list.extend(event_field_list)
886 def get_index(self, field, index):
888 If the field is an array or a sequence, return the element
889 at position index, otherwise return None
891 evDef = ctf.Definition.__new__(ctf.Definition)
893 evDef._d = _bt_ctf_get_index(self._e, field._d, index)
894 except AttributeError:
895 raise TypeError("in get_index, argument 2 must be a "
896 "Definition (field) instance")
902 def get_handle(self):
904 Get the TraceHandle associated with an event
907 ret = _bt_ctf_event_get_handle_id(self._e)
911 th = TraceHandle.__new__(TraceHandle)
915 def get_context(self):
917 Get the context associated with an event.
918 Return None on error.
921 ctx._c = _bt_ctf_event_get_context(self._e);
927 class FieldError(Exception):
928 def __init__(self, value):
932 return repr(self.value)
934 class Definition(object):
935 """Definition class. Do not instantiate."""
938 raise NotImplementedError("ctf.Definition cannot be instantiated")
941 return "Babeltrace Definition: name('{0}'), type({1})".format(
942 self.field_name(), self.field_type())
944 def field_name(self):
945 """Return the name of a field or None on error."""
946 return _bt_ctf_field_name(self._d)
948 def field_type(self):
949 """Return the type of a field or -1 if unknown."""
950 return _bt_ctf_field_type(_bt_ctf_get_decl_from_def(self._d))
952 def get_int_signedness(self):
954 Return the signedness of an integer:
955 0 if unsigned; 1 if signed; -1 on error.
957 return _bt_ctf_get_int_signedness(_bt_ctf_get_decl_from_def(self._d))
959 def get_int_base(self):
960 """Return the base of an int or a negative value on error."""
961 return _bt_ctf_get_int_base(_bt_ctf_get_decl_from_def(self._d))
963 def get_int_byte_order(self):
965 Return the byte order of an int or a negative
968 return _bt_ctf_get_int_byte_order(_bt_ctf_get_decl_from_def(self._d))
970 def get_int_len(self):
972 Return the size, in bits, of an int or a negative
975 return _bt_ctf_get_int_len(_bt_ctf_get_decl_from_def(self._d))
977 def get_enum_str(self):
979 Return the string matching the current enumeration.
980 Return None on error.
982 return _bt_ctf_get_enum_str(self._d)
984 def get_encoding(self):
986 Return the encoding of an int or a string.
987 Return a negative value on error.
989 return _bt_ctf_get_encoding(_bt_ctf_get_decl_from_def(self._d))
991 def get_array_len(self):
993 Return the len of an array or a negative
996 return _bt_ctf_get_array_len(_bt_ctf_get_decl_from_def(self._d))
998 def get_array_element_at(self, index):
1000 Return the array's element at position index.
1001 Return None on error
1003 array = _bt_python_get_array_from_def(self._d)
1007 element = ctf.Definition.__new__(ctf.Definition)
1008 element._d = _bt_array_index(array, index)
1009 if element._d is None:
1013 def get_sequence_len(self):
1015 Return the len of a sequence or a negative
1018 seq = _bt_python_get_sequence_from_def(self._d)
1019 return _bt_sequence_len(seq)
1021 def get_sequence_element_at(self, index):
1023 Return the sequence's element at position index,
1024 otherwise return None
1026 seq = _bt_python_get_sequence_from_def(self._d)
1028 element = ctf.Definition.__new__(ctf.Definition)
1029 element._d = _bt_sequence_index(seq, index)
1030 if element._d is not None:
1034 def get_uint64(self):
1036 Return the value associated with the field.
1037 If the field does not exist or is not of the type requested,
1038 the value returned is undefined. To check if an error occured,
1039 use the ctf.field_error() function after accessing a field.
1041 return _bt_ctf_get_uint64(self._d)
1043 def get_int64(self):
1045 Return the value associated with the field.
1046 If the field does not exist or is not of the type requested,
1047 the value returned is undefined. To check if an error occured,
1048 use the ctf.field_error() function after accessing a field.
1050 return _bt_ctf_get_int64(self._d)
1052 def get_char_array(self):
1054 Return the value associated with the field.
1055 If the field does not exist or is not of the type requested,
1056 the value returned is undefined. To check if an error occured,
1057 use the ctf.field_error() function after accessing a field.
1059 return _bt_ctf_get_char_array(self._d)
1063 Return the value associated with the field.
1064 If the field does not exist or is not of the type requested,
1065 the value returned is undefined. To check if an error occured,
1066 use the ctf.field_error() function after accessing a field.
1068 return _bt_ctf_get_string(self._d)
1070 def get_float(self):
1072 Return the value associated with the field.
1073 If the field does not exist or is not of the type requested,
1074 the value returned is undefined. To check if an error occured,
1075 use the ctf.field_error() function after accessing a field.
1077 return _bt_ctf_get_float(self._d)
1079 def get_variant(self):
1081 Return the variant's selected field.
1082 If the field does not exist or is not of the type requested,
1083 the value returned is undefined. To check if an error occured,
1084 use the ctf.field_error() function after accessing a field.
1086 return _bt_ctf_get_variant(self._d)
1088 def get_struct_field_count(self):
1090 Return the number of fields contained in the structure.
1091 If the field does not exist or is not of the type requested,
1092 the value returned is undefined.
1094 return _bt_ctf_get_struct_field_count(self._d)
1096 def get_struct_field_at(self, i):
1098 Return the structure's field at position i.
1099 If the field does not exist or is not of the type requested,
1100 the value returned is undefined. To check if an error occured,
1101 use the ctf.field_error() function after accessing a field.
1103 return _bt_ctf_get_struct_field_index(self._d, i)
1105 def get_value(self):
1107 Return the value associated with the field according to its type.
1108 Return None on error.
1110 id = self.field_type()
1112 if id == ctf.type_id.STRING:
1113 value = self.get_str()
1114 elif id == ctf.type_id.ARRAY:
1116 for i in range(self.get_array_len()):
1117 element = self.get_array_element_at(i)
1118 value.append(element.get_value())
1119 elif id == ctf.type_id.INTEGER:
1120 if self.get_int_signedness() == 0:
1121 value = self.get_uint64()
1123 value = self.get_int64()
1124 elif id == ctf.type_id.ENUM:
1125 value = self.get_enum_str()
1126 elif id == ctf.type_id.SEQUENCE:
1127 seq_len = self.get_sequence_len()
1129 for i in range(seq_len):
1130 evDef = self.get_sequence_element_at(i)
1131 value.append(evDef.get_value())
1132 elif id == ctf.type_id.FLOAT:
1133 value = self.get_float()
1134 elif id == ctf.type_id.VARIANT:
1135 variant = ctf.Definition.__new__(ctf.Definition)
1136 variant._d = self.get_variant();
1137 value = variant.get_value()
1138 elif id == ctf.type_id.STRUCT:
1140 for i in range(self.get_struct_field_count()):
1141 member = ctf.Definition.__new__(ctf.Definition)
1142 member._d = self.get_struct_field_at(i);
1143 value[member.field_name()] = member.get_value()
1145 if ctf.field_error():
1146 raise ctf.FieldError("Error occured while accessing field {} of type {}".format(self.field_name(), ctf.type_id.get_type_id_name(self.field_type())))
1149 def get_scope(self):
1150 """Return the scope of a field or None on error."""
1153 class EventDecl(object):
1154 """Event declaration class. Do not instantiate."""
1157 raise NotImplementedError("ctf.EventDecl cannot be instantiated")
1160 return "Babeltrace EventDecl: name {0}".format(self.get_name())
1163 """Return the name of the event or None on error"""
1164 return _bt_ctf_get_decl_event_name(self._d)
1166 def get_decl_fields(self, scope):
1168 Return a list of ctf.FieldDecl
1169 Return None on error.
1171 ptr_list = _by_python_field_decl_listcaller(self._d, scope)
1173 if ptr_list is None:
1179 tmp = ctf.FieldDecl.__new__(ctf.FieldDecl)
1180 tmp._d = _bt_python_field_decl_one_from_list(
1184 #Last item of list is None
1187 decl_list.append(tmp)
1192 class FieldDecl(object):
1193 """Field declaration class. Do not instantiate."""
1196 raise NotImplementedError("ctf.FieldDecl cannot be instantiated")
1199 return "Babeltrace FieldDecl: name {0}".format(self.get_name())
1202 """Return the name of a FieldDecl or None on error"""
1203 return _bt_ctf_get_decl_field_name(self._d)
1209 Return the last error code encountered while
1210 accessing a field and reset the error flag.
1211 Return 0 if no error, a negative value otherwise.
1213 return _bt_ctf_field_get_error()
1216 def get_event_decl_list(trace_handle, context):
1218 Return a list of ctf.EventDecl
1219 Return None on error.
1222 handle_id = trace_handle._id
1223 except AttributeError:
1224 raise TypeError("in get_event_decl_list, "
1225 "argument 1 must be a TraceHandle instance")
1227 ptr_list, count = _bt_python_event_decl_listcaller(handle_id, context._c)
1228 except AttributeError:
1229 raise TypeError("in get_event_decl_list, "
1230 "argument 2 must be a Context instance")
1232 if ptr_list is None:
1236 for i in range(count):
1237 tmp = ctf.EventDecl.__new__(ctf.EventDecl)
1238 tmp._d = _bt_python_decl_one_from_list(ptr_list, i)
1239 decl_list.append(tmp)
1247 // =================================================================
1249 // File and list-related
1250 // python-complements.h
1251 // =================================================================
1257 Open a file for babeltrace.
1259 file_path is a string containing the path or None to use the
1260 standard output in writing mode.
1262 The mode can be 'r', 'w' or 'a' for reading (default), writing or
1263 appending. The file will be created if it doesn't exist when
1264 opened for writing or appending; it will be truncated when opened
1265 for writing. Add a 'b' to the mode for binary files. Add a '+'
1266 to the mode to allow simultaneous reading and writing.
1269 def __new__(cls, file_path, mode='r'):
1270 # __new__ is used to control the return value
1271 # as the File class should return None
1272 # if _bt_file_open returns NULL
1275 if file_path is not None and type(file_path) is not str:
1276 raise TypeError("in method __init__, argument 2 of type 'str'")
1277 if type(mode) is not str:
1278 raise TypeError("in method __init__, argument 3 of type 'str'")
1281 file_ptr = _bt_file_open(file_path, mode)
1282 if file_ptr is None:
1285 # Class instantiation
1286 file_inst = super(File, cls).__new__(cls)
1287 file_inst._file = file_ptr
1290 def __init__(self, file_path, mode='r'):
1292 self._use_stdout = False
1294 if file_path is None:
1296 file_path = "stdout"
1298 self._use_stdout = True
1300 self._file_path = file_path
1311 return "{0} babeltrace File; file_path('{1}'), mode('{2}')".format(
1312 stat, self._file_path, self._mode)
1315 """Close the file. Is also called using del."""
1316 if self._opened and not self._use_stdout:
1317 _bt_file_close(self._file)
1318 self._opened = False