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