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);
655 class CTFStringEncoding:
661 #enum equivalent, accessible constants
662 #These are taken directly from ctf/events.h
663 #All changes to enums must also be made here
677 def get_type_name(id):
679 constants = [attr for attr in dir(CTFTypeId) if not callable(getattr(CTFTypeId, attr)) and not attr.startswith("__")]
680 for attr in constants:
681 if getattr(CTFTypeId, attr) == id:
688 TRACE_PACKET_HEADER = 0
689 STREAM_PACKET_CONTEXT = 1
690 STREAM_EVENT_HEADER = 2
691 STREAM_EVENT_CONTEXT = 3
695 class string_encoding:
701 class Iterator(Iterator, object):
703 Allocate a CTF trace collection iterator.
705 begin_pos and end_pos are optional parameters to specify the
706 position at which the trace collection should be seeked upon
707 iterator creation, and the position at which iteration will
708 start returning "EOF".
710 By default, if begin_pos is None, a SEEK_CUR is performed at
711 creation. By default, if end_pos is None, a SEEK_END (end of
712 trace) is the EOF criterion.
714 Only one iterator can be created against a context. If more than one
715 iterator is being created for the same context, the second creation
716 will return None. The previous iterator must be destroyed before
717 creation of the new iterator for this function to succeed.
720 def __new__(cls, context, begin_pos = None, end_pos = None):
721 # __new__ is used to control the return value
722 # as the CTFReader.Iterator class should return None
723 # if bt_ctf_iter_create returns NULL
725 if begin_pos is None:
734 it = _bt_ctf_iter_create(context._c, bp, ep)
735 except AttributeError:
736 raise TypeError("in __init__, "
737 "argument 2 must be a Context instance")
741 ret_class = super(CTFReader.Iterator, cls).__new__(cls)
745 def __init__(self, context, begin_pos = None, end_pos = None):
746 Iterator.__init__(self, None, None, None,
747 _bt_ctf_get_iter(self._i))
750 _bt_ctf_iter_destroy(self._i)
752 def read_event(self):
754 Read the iterator's current event data.
755 Return current event on success, None on end of trace.
757 ret = _bt_ctf_iter_read_event(self._i)
760 ev = CTFReader.Event.__new__(CTFReader.Event)
767 This class represents an event from the trace.
768 It is obtained with read_event() from CTFReader.Iterator.
773 raise NotImplementedError("CTFReader.Event cannot be instantiated")
775 def get_top_level_scope(self, scope):
777 Return a definition of the top-level scope
778 Top-level scopes are defined in CTFReader.scope.
779 In order to get a field or a field list, the user needs to pass a
780 scope as argument, this scope can be a top-level scope or a scope
781 relative to an arbitrary field. This function provides the mapping
782 between the scope and the actual definition of top-level scopes.
783 On error return None.
785 evDef = CTFReader.Definition.__new__(CTFReader.Definition)
786 evDef._d = _bt_ctf_get_top_level_scope(self._e, scope)
792 """Return the name of the event or None on error."""
793 return _bt_ctf_event_name(self._e)
795 def get_cycles(self):
797 Return the timestamp of the event as written in
798 the packet (in cycles) or -1ULL on error.
800 return _bt_ctf_get_cycles(self._e)
802 def get_timestamp(self):
804 Return the timestamp of the event offsetted with the
805 system clock source or -1ULL on error.
807 return _bt_ctf_get_timestamp(self._e)
809 def get_field_with_scope(self, scope, field):
811 Return the definition of a specific field.
812 Return None on error.
814 evDef = CTFReader.Definition.__new__(CTFReader.Definition)
816 evDef._d = _bt_ctf_get_field(self._e, scope._d, field)
817 except AttributeError:
818 raise TypeError("in get_field, argument 2 must be a "
819 "Definition (scope) instance")
825 def get_field(self, field):
827 Return the definition of fields by a name
830 eventScope = self.get_top_level_scope(CTFReader.scope.EVENT_FIELDS)
831 streamScope = self.get_top_level_scope(CTFReader.scope.STREAM_EVENT_CONTEXT)
834 if eventScope is not None:
835 evDef = self.get_field_with_scope(eventScope, field)
836 if evDef is not None:
837 fields_by_name.append(evDef)
839 if streamScope is not None:
840 evDef = self.get_field_with_scope(streamScope, field)
841 if evDef is not None:
842 fields_by_name.append(evDef);
844 if not fields_by_name:
846 return fields_by_name
848 def get_field_list_with_scope(self, scope):
850 Return a list of Definitions associated with the scope
851 Return None on error.
854 field_lc, count = _bt_python_field_listcaller(self._e, scope._d)
855 except AttributeError:
856 raise TypeError("in get_field_list, argument 2 must be a "
857 "Definition (scope) instance")
863 for i in range(count):
864 tmp = CTFReader.Definition.__new__(CTFReader.Definition)
865 tmp._d = _bt_python_field_one_from_list(field_lc, i)
871 def get_field_list(self):
872 """Return a list of Definitions or None on error."""
873 eventScope = self.get_top_level_scope(CTFReader.scope.EVENT_FIELDS)
874 streamScope = self.get_top_level_scope(CTFReader.scope.STREAM_EVENT_CONTEXT)
877 if eventScope is not None:
878 event_field_list = self.get_field_list_with_scope(eventScope)
879 if event_field_list is not None:
880 def_list = event_field_list
882 if streamScope is not None:
883 event_field_list = self.get_field_list_with_scope(streamScope)
884 if event_field_list is not None:
885 def_list.extend(event_field_list)
891 def get_index(self, field, index):
893 If the field is an array or a sequence, return the element
894 at position index, otherwise return None
896 evDef = CTFReader.Definition.__new__(CTFReader.Definition)
898 evDef._d = _bt_ctf_get_index(self._e, field._d, index)
899 except AttributeError:
900 raise TypeError("in get_index, argument 2 must be a "
901 "Definition (field) instance")
907 def get_handle(self):
909 Get the TraceHandle associated with an event
912 ret = _bt_ctf_event_get_handle_id(self._e)
916 th = TraceHandle.__new__(TraceHandle)
920 def get_context(self):
922 Get the context associated with an event.
923 Return None on error.
926 ctx._c = _bt_ctf_event_get_context(self._e);
932 class FieldError(Exception):
933 def __init__(self, value):
937 return repr(self.value)
939 class Definition(object):
940 """Definition class. Do not instantiate."""
943 raise NotImplementedError("CTFReader.Definition cannot be instantiated")
946 return "Babeltrace Definition: name('{0}'), type({1})".format(
947 self.field_name(), self.field_type())
949 def field_name(self):
950 """Return the name of a field or None on error."""
951 return _bt_ctf_field_name(self._d)
953 def field_type(self):
954 """Return the type of a field or -1 if unknown."""
955 return _bt_ctf_field_type(_bt_ctf_get_decl_from_def(self._d))
957 def get_int_signedness(self):
959 Return the signedness of an integer:
960 0 if unsigned; 1 if signed; -1 on error.
962 return _bt_ctf_get_int_signedness(_bt_ctf_get_decl_from_def(self._d))
964 def get_int_base(self):
965 """Return the base of an int or a negative value on error."""
966 return _bt_ctf_get_int_base(_bt_ctf_get_decl_from_def(self._d))
968 def get_int_byte_order(self):
970 Return the byte order of an int or a negative
973 return _bt_ctf_get_int_byte_order(_bt_ctf_get_decl_from_def(self._d))
975 def get_int_len(self):
977 Return the size, in bits, of an int or a negative
980 return _bt_ctf_get_int_len(_bt_ctf_get_decl_from_def(self._d))
982 def get_enum_str(self):
984 Return the string matching the current enumeration.
985 Return None on error.
987 return _bt_ctf_get_enum_str(self._d)
989 def get_encoding(self):
991 Return the encoding of an int or a string.
992 Return a negative value on error.
994 return _bt_ctf_get_encoding(_bt_ctf_get_decl_from_def(self._d))
996 def get_array_len(self):
998 Return the len of an array or a negative
1001 return _bt_ctf_get_array_len(_bt_ctf_get_decl_from_def(self._d))
1003 def get_array_element_at(self, index):
1005 Return the array's element at position index.
1006 Return None on error
1008 array = _bt_python_get_array_from_def(self._d)
1012 element = CTFReader.Definition.__new__(CTFReader.Definition)
1013 element._d = _bt_array_index(array, index)
1014 if element._d is None:
1018 def get_sequence_len(self):
1020 Return the len of a sequence or a negative
1023 seq = _bt_python_get_sequence_from_def(self._d)
1024 return _bt_sequence_len(seq)
1026 def get_sequence_element_at(self, index):
1028 Return the sequence's element at position index,
1029 otherwise return None
1031 seq = _bt_python_get_sequence_from_def(self._d)
1033 element = CTFReader.Definition.__new__(CTFReader.Definition)
1034 element._d = _bt_sequence_index(seq, index)
1035 if element._d is not None:
1039 def get_uint64(self):
1041 Return the value associated with the field.
1042 If the field does not exist or is not of the type requested,
1043 the value returned is undefined. To check if an error occured,
1044 use the CTFReader.field_error() function after accessing a field.
1046 return _bt_ctf_get_uint64(self._d)
1048 def get_int64(self):
1050 Return the value associated with the field.
1051 If the field does not exist or is not of the type requested,
1052 the value returned is undefined. To check if an error occured,
1053 use the CTFReader.field_error() function after accessing a field.
1055 return _bt_ctf_get_int64(self._d)
1057 def get_char_array(self):
1059 Return the value associated with the field.
1060 If the field does not exist or is not of the type requested,
1061 the value returned is undefined. To check if an error occured,
1062 use the CTFReader.field_error() function after accessing a field.
1064 return _bt_ctf_get_char_array(self._d)
1068 Return the value associated with the field.
1069 If the field does not exist or is not of the type requested,
1070 the value returned is undefined. To check if an error occured,
1071 use the CTFReader.field_error() function after accessing a field.
1073 return _bt_ctf_get_string(self._d)
1075 def get_float(self):
1077 Return the value associated with the field.
1078 If the field does not exist or is not of the type requested,
1079 the value returned is undefined. To check if an error occured,
1080 use the CTFReader.field_error() function after accessing a field.
1082 return _bt_ctf_get_float(self._d)
1084 def get_variant(self):
1086 Return the variant's selected field.
1087 If the field does not exist or is not of the type requested,
1088 the value returned is undefined. To check if an error occured,
1089 use the CTFReader.field_error() function after accessing a field.
1091 return _bt_ctf_get_variant(self._d)
1093 def get_struct_field_count(self):
1095 Return the number of fields contained in the structure.
1096 If the field does not exist or is not of the type requested,
1097 the value returned is undefined.
1099 return _bt_ctf_get_struct_field_count(self._d)
1101 def get_struct_field_at(self, i):
1103 Return the structure's field at position i.
1104 If the field does not exist or is not of the type requested,
1105 the value returned is undefined. To check if an error occured,
1106 use the CTFReader.field_error() function after accessing a field.
1108 return _bt_ctf_get_struct_field_index(self._d, i)
1110 def get_value(self):
1112 Return the value associated with the field according to its type.
1113 Return None on error.
1115 id = self.field_type()
1117 if id == CTFTypeId.STRING:
1118 value = self.get_str()
1119 elif id == CTFTypeId.ARRAY:
1121 for i in range(self.get_array_len()):
1122 element = self.get_array_element_at(i)
1123 value.append(element.get_value())
1124 elif id == CTFTypeId.INTEGER:
1125 if self.get_int_signedness() == 0:
1126 value = self.get_uint64()
1128 value = self.get_int64()
1129 elif id == CTFTypeId.ENUM:
1130 value = self.get_enum_str()
1131 elif id == CTFTypeId.SEQUENCE:
1132 seq_len = self.get_sequence_len()
1134 for i in range(seq_len):
1135 evDef = self.get_sequence_element_at(i)
1136 value.append(evDef.get_value())
1137 elif id == CTFTypeId.FLOAT:
1138 value = self.get_float()
1139 elif id == CTFTypeId.VARIANT:
1140 variant = CTFReader.Definition.__new__(CTFReader.Definition)
1141 variant._d = self.get_variant();
1142 value = variant.get_value()
1143 elif id == CTFTypeId.STRUCT:
1145 for i in range(self.get_struct_field_count()):
1146 member = CTFReader.Definition.__new__(CTFReader.Definition)
1147 member._d = self.get_struct_field_at(i);
1148 value[member.field_name()] = member.get_value()
1150 if CTFReader.field_error():
1151 raise CTFReader.FieldError("Error occured while accessing field {} of type {}".format(self.field_name(), CTFTypeId.get_type_name(self.field_type())))
1154 def get_scope(self):
1155 """Return the scope of a field or None on error."""
1158 class EventDecl(object):
1159 """Event declaration class. Do not instantiate."""
1162 raise NotImplementedError("CTFReader.EventDecl cannot be instantiated")
1165 return "Babeltrace EventDecl: name {0}".format(self.get_name())
1168 """Return the name of the event or None on error"""
1169 return _bt_ctf_get_decl_event_name(self._d)
1171 def get_decl_fields(self, scope):
1173 Return a list of CTFReader.FieldDecl
1174 Return None on error.
1176 ptr_list = _by_python_field_decl_listcaller(self._d, scope)
1178 if ptr_list is None:
1184 tmp = CTFReader.FieldDecl.__new__(CTFReader.FieldDecl)
1185 tmp._d = _bt_python_field_decl_one_from_list(
1189 #Last item of list is None
1192 decl_list.append(tmp)
1197 class FieldDecl(object):
1198 """Field declaration class. Do not instantiate."""
1201 raise NotImplementedError("CTFReader.FieldDecl cannot be instantiated")
1204 return "Babeltrace FieldDecl: name {0}".format(self.get_name())
1207 """Return the name of a FieldDecl or None on error"""
1208 return _bt_ctf_get_decl_field_name(self._d)
1214 Return the last error code encountered while
1215 accessing a field and reset the error flag.
1216 Return 0 if no error, a negative value otherwise.
1218 return _bt_ctf_field_get_error()
1221 def get_event_decl_list(trace_handle, context):
1223 Return a list of CTFReader.EventDecl
1224 Return None on error.
1227 handle_id = trace_handle._id
1228 except AttributeError:
1229 raise TypeError("in get_event_decl_list, "
1230 "argument 1 must be a TraceHandle instance")
1232 ptr_list, count = _bt_python_event_decl_listcaller(handle_id, context._c)
1233 except AttributeError:
1234 raise TypeError("in get_event_decl_list, "
1235 "argument 2 must be a Context instance")
1237 if ptr_list is None:
1241 for i in range(count):
1242 tmp = CTFReader.EventDecl.__new__(CTFReader.EventDecl)
1243 tmp._d = _bt_python_decl_one_from_list(ptr_list, i)
1244 decl_list.append(tmp)
1252 // =================================================================
1254 // File and list-related
1255 // python-complements.h
1256 // =================================================================
1262 Open a file for babeltrace.
1264 file_path is a string containing the path or None to use the
1265 standard output in writing mode.
1267 The mode can be 'r', 'w' or 'a' for reading (default), writing or
1268 appending. The file will be created if it doesn't exist when
1269 opened for writing or appending; it will be truncated when opened
1270 for writing. Add a 'b' to the mode for binary files. Add a '+'
1271 to the mode to allow simultaneous reading and writing.
1274 def __new__(cls, file_path, mode='r'):
1275 # __new__ is used to control the return value
1276 # as the File class should return None
1277 # if _bt_file_open returns NULL
1280 if file_path is not None and type(file_path) is not str:
1281 raise TypeError("in method __init__, argument 2 of type 'str'")
1282 if type(mode) is not str:
1283 raise TypeError("in method __init__, argument 3 of type 'str'")
1286 file_ptr = _bt_file_open(file_path, mode)
1287 if file_ptr is None:
1290 # Class instantiation
1291 file_inst = super(File, cls).__new__(cls)
1292 file_inst._file = file_ptr
1295 def __init__(self, file_path, mode='r'):
1297 self._use_stdout = False
1299 if file_path is None:
1301 file_path = "stdout"
1303 self._use_stdout = True
1305 self._file_path = file_path
1316 return "{0} babeltrace File; file_path('{1}'), mode('{2}')".format(
1317 stat, self._file_path, self._mode)
1320 """Close the file. Is also called using del."""
1321 if self._opened and not self._use_stdout:
1322 _bt_file_close(self._file)
1323 self._opened = False