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