bindings/python/babeltrace.i.in

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