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 %pythoncode %{
 198
 199 def print_format_list(babeltrace_file):
 200         """
 201         Print a list of available formats to file.
 202
 203         babeltrace_file must be a File instance opened in write mode.
 204         """
 205         try:
 206                 if babeltrace_file._file is not None:
 207                         _bt_print_format_list(babeltrace_file._file)
 208         except AttributeError:
 209                 raise TypeError("in print_format_list, "
 210                         "argument 1 must be a File instance")
 211
 212 %}
 213
 214
 215 /* =================================================================
 216                 ITERATOR.H, ITERATOR-INTERNAL.H
 217                 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
 218 */
 219
 220 %rename("_bt_iter_create") bt_iter_create(struct bt_context *ctx,
 221                 const struct bt_iter_pos *begin_pos, const struct bt_iter_pos *end_pos);
 222 %rename("_bt_iter_destroy") bt_iter_destroy(struct bt_iter *iter);
 223 %rename("_bt_iter_next") bt_iter_next(struct bt_iter *iter);
 224 %rename("_bt_iter_get_pos") bt_iter_get_pos(struct bt_iter *iter);
 225 %rename("_bt_iter_free_pos") bt_iter_free_pos(struct bt_iter_pos *pos);
 226 %rename("_bt_iter_set_pos") bt_iter_set_pos(struct bt_iter *iter,
 227                 const struct bt_iter_pos *pos);
 228 %rename("_bt_iter_create_time_pos") bt_iter_create_time_pos(struct bt_iter *iter,
 229                 uint64_t timestamp);
 230
 231 struct bt_iter *bt_iter_create(struct bt_context *ctx,
 232                 const struct bt_iter_pos *begin_pos, const struct bt_iter_pos *end_pos);
 233 void bt_iter_destroy(struct bt_iter *iter);
 234 int bt_iter_next(struct bt_iter *iter);
 235 struct bt_iter_pos *bt_iter_get_pos(struct bt_iter *iter);
 236 void bt_iter_free_pos(struct bt_iter_pos *pos);
 237 int bt_iter_set_pos(struct bt_iter *iter, const struct bt_iter_pos *pos);
 238 struct bt_iter_pos *bt_iter_create_time_pos(struct bt_iter *iter, uint64_t timestamp);
 239
 240 %rename("_bt_iter_pos") bt_iter_pos;
 241 %rename("SEEK_TIME") BT_SEEK_TIME;
 242 %rename("SEEK_RESTORE") BT_SEEK_RESTORE;
 243 %rename("SEEK_CUR") BT_SEEK_CUR;
 244 %rename("SEEK_BEGIN") BT_SEEK_BEGIN;
 245 %rename("SEEK_LAST") BT_SEEK_LAST;
 246
 247 // This struct is taken from iterator.h
 248 // All changes to the struct must also be made here
 249 struct bt_iter_pos {
 250         enum {
 251                 BT_SEEK_TIME,           /* uses u.seek_time */
 252                 BT_SEEK_RESTORE,        /* uses u.restore */
 253                 BT_SEEK_CUR,
 254                 BT_SEEK_BEGIN,
 255                 BT_SEEK_LAST
 256         } type;
 257         union {
 258                 uint64_t seek_time;
 259                 struct bt_saved_pos *restore;
 260         } u;
 261 };
 262
 263
 264 %pythoncode%{
 265
 266 class IterPos:
 267         """This class represents the position where to set an iterator."""
 268
 269         __can_access = False
 270
 271         def __init__(self, seek_type, seek_time = None):
 272                 """
 273                 seek_type represents the type of seek to use.
 274                 seek_time is the timestamp to seek to when using SEEK_TIME, it
 275                 is expressed in nanoseconds
 276                 Only use SEEK_RESTORE on IterPos obtained from the get_pos function
 277                 in Iter class.
 278                 """
 279
 280                 self._pos = _bt_iter_pos()
 281                 self._pos.type = seek_type
 282                 if seek_time and seek_type == SEEK_TIME:
 283                         self._pos.u.seek_time = seek_time
 284                 self.__can_access = True
 285
 286         def __del__(self):
 287                 if not self.__can_access:
 288                         _bt_iter_free_pos(self._pos)
 289
 290         def _get_type(self):
 291                 if not __can_access:
 292                         raise AttributeError("seek_type is not available")
 293                 return self._pos.type
 294
 295         def _set_type(self, seek_type):
 296                 if not __can_access:
 297                         raise AttributeError("seek_type is not available")
 298                 self._pos.type = seek_type
 299
 300         def _get_time(self):
 301                 if not __can_access:
 302                         raise AttributeError("seek_time is not available")
 303
 304                 elif self._pos.type is not SEEK_TIME:
 305                         raise TypeError("seek_type is not SEEK_TIME")
 306
 307                 return self._pos.u.seek_time
 308
 309         def _set_time(self, time):
 310                 if not __can_access:
 311                         raise AttributeError("seek_time is not available")
 312
 313                 elif self._pos.type is not SEEK_TIME:
 314                         raise TypeError("seek_type is not SEEK_TIME")
 315
 316                 self._pos.u.seek_time = time
 317
 318         def _get_pos(self):
 319                 return self._pos
 320
 321
 322         seek_type = property(_get_type, _set_type)
 323         seek_time = property(_get_time, _set_time)
 324
 325
 326 class Iterator:
 327
 328         __with_init = False
 329
 330         def __init__(self, context, begin_pos = None, end_pos = None, _no_init = None):
 331                 """
 332                 Allocate a trace collection iterator.
 333
 334                 begin_pos and end_pos are optional parameters to specify the
 335                 position at which the trace collection should be seeked upon
 336                 iterator creation, and the position  at which iteration will
 337                 start returning "EOF".
 338
 339                 By default, if begin_pos is None, a BT_SEEK_CUR is performed at
 340                 creation. By default, if end_pos is None, a BT_SEEK_END (end of
 341                 trace) is the EOF criterion.
 342                 """
 343                 if _no_init is None:
 344                         if begin_pos is None:
 345                                 bp = None
 346                         else:
 347                                 try:
 348                                         bp = begin_pos._pos
 349                                 except AttributeError:
 350                                         raise TypeError("in __init__, "
 351                                                 "argument 3 must be a IterPos instance")
 352
 353                         if end_pos is None:
 354                                 ep = None
 355                         else:
 356                                 try:
 357                                         ep = end_pos._pos
 358                                 except AttributeError:
 359                                         raise TypeError("in __init__, "
 360                                                 "argument 4 must be a IterPos instance")
 361
 362                         try:
 363                                 self._bi = _bt_iter_create(context._c, bp, ep)
 364                         except AttributeError:
 365                                 raise TypeError("in __init__, "
 366                                         "argument 2 must be a Context instance")
 367
 368                         self.__with_init = True
 369
 370                 else:
 371                         self._bi = _no_init
 372
 373         def __del__(self):
 374                 if self.__with_init:
 375                         _bt_iter_destroy(self._bi)
 376
 377         def next(self):
 378                 """
 379                 Move trace collection position to the next event.
 380                 Returns 0 on success, a negative value on error.
 381                 """
 382                 return _bt_iter_next(self._bi)
 383
 384         def get_pos(self):
 385                 """Return a IterPos class of the current iterator position."""
 386                 ret = IterPos(0)
 387                 ret.__can_access = False
 388                 ret._pos = _bt_iter_get_pos(self._bi)
 389                 return ret
 390
 391         def set_pos(self, pos):
 392                 """
 393                 Move the iterator to a given position.
 394
 395                 On error, the stream_heap is reinitialized and returned empty.
 396                 Return 0 for success.
 397                 Return EOF if the position requested is after the last event of the
 398                 trace collection.
 399                 Return -EINVAL when called with invalid parameter.
 400                 Return -ENOMEM if the stream_heap could not be properly initialized.
 401                 """
 402                 try:
 403                         return _bt_iter_set_pos(self._bi, pos._pos)
 404                 except AttributeError:
 405                         raise TypeError("in set_pos, "
 406                                 "argument 2 must be a IterPos instance")
 407
 408         def create_time_pos(self, timestamp):
 409                 """
 410                 Create a position based on time
 411                 This function allocates and returns a new IterPos to be able to
 412                 restore an iterator position based on a timestamp.
 413                 """
 414
 415                 if timestamp < 0:
 416                         raise TypeError("timestamp must be an unsigned int")
 417
 418                 ret = IterPos(0)
 419                 ret.__can_access = False
 420                 ret._pos = _bt_iter_create_time_pos(self._bi, timestamp)
 421                 return ret
 422 %}
 423
 424
 425 /* =================================================================
 426                 CLOCK-TYPE.H
 427                 ¯¯¯¯¯¯¯¯¯¯¯¯
 428         *** Enum copied from clock-type.h
 429                 All changes must also be made here
 430 */
 431 %rename("CLOCK_CYCLES") BT_CLOCK_CYCLES;
 432 %rename("CLOCK_REAL") BT_CLOCK_REAL;
 433
 434 enum bt_clock_type {
 435         BT_CLOCK_CYCLES = 0,
 436         BT_CLOCK_REAL
 437 };
 438
 439 /* =================================================================
 440                 TRACE-HANDLE.H, TRACE-HANDLE-INTERNAL.H
 441                 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
 442 */
 443
 444 %rename("_bt_trace_handle_create") bt_trace_handle_create(struct bt_context *ctx);
 445 %rename("_bt_trace_handle_destroy") bt_trace_handle_destroy(struct bt_trace_handle *bt);
 446 struct bt_trace_handle *bt_trace_handle_create(struct bt_context *ctx);
 447 void bt_trace_handle_destroy(struct bt_trace_handle *bt);
 448
 449 %rename("_bt_trace_handle_get_path") bt_trace_handle_get_path(struct bt_context *ctx,
 450                 int handle_id);
 451 %rename("_bt_trace_handle_get_timestamp_begin") bt_trace_handle_get_timestamp_begin(
 452                 struct bt_context *ctx, int handle_id, enum bt_clock_type type);
 453 %rename("_bt_trace_handle_get_timestamp_end") bt_trace_handle_get_timestamp_end(
 454                 struct bt_context *ctx, int handle_id, enum bt_clock_type type);
 455 %rename("_bt_trace_handle_get_id") bt_trace_handle_get_id(struct bt_trace_handle *th);
 456 int bt_trace_handle_get_id(struct bt_trace_handle *th);
 457 const char *bt_trace_handle_get_path(struct bt_context *ctx, int handle_id);
 458 uint64_t bt_trace_handle_get_timestamp_begin(struct bt_context *ctx, int handle_id,
 459                 enum bt_clock_type type);
 460 uint64_t bt_trace_handle_get_timestamp_end(struct bt_context *ctx, int handle_id,
 461                 enum bt_clock_type type);
 462
 463 %rename("_bt_ctf_event_get_handle_id") bt_ctf_event_get_handle_id(
 464                 const struct bt_ctf_event *event);
 465 int bt_ctf_event_get_handle_id(const struct bt_ctf_event *event);
 466
 467
 468 %pythoncode%{
 469
 470 class TraceHandle(object):
 471         """
 472         The TraceHandle allows the user to manipulate a trace file directly.
 473         It is a unique identifier representing a trace file.
 474         Do not instantiate.
 475         """
 476
 477         def __init__(self):
 478                 raise NotImplementedError("TraceHandle cannot be instantiated")
 479
 480         def __repr__(self):
 481                 return "Babeltrace TraceHandle: trace_id('{}')".format(self._id)
 482
 483         def get_id(self):
 484                 """Return the TraceHandle id."""
 485                 return self._id
 486
 487         def get_path(self, context):
 488                 """Return the path of a TraceHandle."""
 489                 try:
 490                         return _bt_trace_handle_get_path(context._c, self._id)
 491                 except AttributeError:
 492                         raise TypeError("in get_path, "
 493                                 "argument 2 must be a Context instance")
 494
 495         def get_timestamp_begin(self, context, clock_type):
 496                 """Return the creation time of the buffers of a trace."""
 497                 try:
 498                         return _bt_trace_handle_get_timestamp_begin(
 499                                 context._c, self._id,clock_type)
 500                 except AttributeError:
 501                         raise TypeError("in get_timestamp_begin, "
 502                                 "argument 2 must be a Context instance")
 503
 504         def get_timestamp_end(self, context, clock_type):
 505                 """Return the destruction timestamp of the buffers of a trace."""
 506                 try:
 507                         return _bt_trace_handle_get_timestamp_end(
 508                                 context._c, self._id, clock_type)
 509                 except AttributeError:
 510                         raise TypeError("in get_timestamp_end, "
 511                                 "argument 2 must be a Context instance")
 512
 513 %}
 514
 515
 516
 517 // =================================================================
 518 //                              CTF
 519 // =================================================================
 520
 521 /* =================================================================
 522                 ITERATOR.H, EVENTS.H
 523                 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
 524 */
 525
 526 //Iterator
 527 %rename("_bt_ctf_iter_create") bt_ctf_iter_create(struct bt_context *ctx,
 528                 const struct bt_iter_pos *begin_pos,
 529                 const struct bt_iter_pos *end_pos);
 530 %rename("_bt_ctf_get_iter") bt_ctf_get_iter(struct bt_ctf_iter *iter);
 531 %rename("_bt_ctf_iter_destroy") bt_ctf_iter_destroy(struct bt_ctf_iter *iter);
 532 %rename("_bt_ctf_iter_read_event") bt_ctf_iter_read_event(struct bt_ctf_iter *iter);
 533
 534 struct bt_ctf_iter *bt_ctf_iter_create(struct bt_context *ctx,
 535                 const struct bt_iter_pos *begin_pos,
 536                 const struct bt_iter_pos *end_pos);
 537 struct bt_iter *bt_ctf_get_iter(struct bt_ctf_iter *iter);
 538 void bt_ctf_iter_destroy(struct bt_ctf_iter *iter);
 539 struct bt_ctf_event *bt_ctf_iter_read_event(struct bt_ctf_iter *iter);
 540
 541
 542 //Events
 543
 544 %rename("_bt_ctf_get_top_level_scope") bt_ctf_get_top_level_scope(const struct
 545                 bt_ctf_event *event, enum bt_ctf_scope scope);
 546 %rename("_bt_ctf_event_name") bt_ctf_event_name(const struct bt_ctf_event *ctf_event);
 547 %rename("_bt_ctf_get_timestamp") bt_ctf_get_timestamp(
 548                 const struct bt_ctf_event *ctf_event);
 549 %rename("_bt_ctf_get_cycles") bt_ctf_get_cycles(
 550                 const struct bt_ctf_event *ctf_event);
 551
 552 %rename("_bt_ctf_get_field") bt_ctf_get_field(const struct bt_ctf_event *ctf_event,
 553                 const struct definition *scope, const char *field);
 554 %rename("_bt_ctf_get_index") bt_ctf_get_index(const struct bt_ctf_event *ctf_event,
 555                 const struct definition *field, unsigned int index);
 556 %rename("_bt_ctf_field_name") bt_ctf_field_name(const struct definition *field);
 557 %rename("_bt_ctf_field_type") bt_ctf_field_type(const struct declaration *field);
 558 %rename("_bt_ctf_get_int_signedness") bt_ctf_get_int_signedness(
 559                 const struct declaration *field);
 560 %rename("_bt_ctf_get_int_base") bt_ctf_get_int_base(const struct declaration *field);
 561 %rename("_bt_ctf_get_int_byte_order") bt_ctf_get_int_byte_order(
 562                 const struct declaration *field);
 563 %rename("_bt_ctf_get_int_len") bt_ctf_get_int_len(const struct declaration *field);
 564 %rename("_bt_ctf_get_encoding") bt_ctf_get_encoding(const struct declaration *field);
 565 %rename("_bt_ctf_get_array_len") bt_ctf_get_array_len(const struct declaration *field);
 566 %rename("_bt_ctf_get_uint64") bt_ctf_get_uint64(const struct definition *field);
 567 %rename("_bt_ctf_get_int64") bt_ctf_get_int64(const struct definition *field);
 568 %rename("_bt_ctf_get_char_array") bt_ctf_get_char_array(const struct definition *field);
 569 %rename("_bt_ctf_get_string") bt_ctf_get_string(const struct definition *field);
 570 %rename("_bt_ctf_field_get_error") bt_ctf_field_get_error(void);
 571 %rename("_bt_ctf_get_decl_event_name") bt_ctf_get_decl_event_name(const struct
 572                 bt_ctf_event_decl *event);
 573 %rename("_bt_ctf_get_decl_field_name") bt_ctf_get_decl_field_name(
 574                 const struct bt_ctf_field_decl *field);
 575 %rename("_bt_ctf_get_decl_from_def") bt_ctf_get_decl_from_def(
 576                 const struct definition *field);
 577
 578 const struct definition *bt_ctf_get_top_level_scope(const struct bt_ctf_event *ctf_event,
 579                 enum bt_ctf_scope scope);
 580 const char *bt_ctf_event_name(const struct bt_ctf_event *ctf_event);
 581 uint64_t bt_ctf_get_timestamp(const struct bt_ctf_event *ctf_event);
 582 uint64_t bt_ctf_get_cycles(const struct bt_ctf_event *ctf_event);
 583 const struct definition *bt_ctf_get_field(const struct bt_ctf_event *ctf_event,
 584                 const struct definition *scope,
 585                 const char *field);
 586 const struct definition *bt_ctf_get_index(const struct bt_ctf_event *ctf_event,
 587                 const struct definition *field,
 588                 unsigned int index);
 589 const char *bt_ctf_field_name(const struct definition *field);
 590 enum ctf_type_id bt_ctf_field_type(const struct declaration *field);
 591 int bt_ctf_get_int_signedness(const struct declaration *field);
 592 int bt_ctf_get_int_base(const struct declaration *field);
 593 int bt_ctf_get_int_byte_order(const struct declaration *field);
 594 ssize_t bt_ctf_get_int_len(const struct declaration *field);
 595 enum ctf_string_encoding bt_ctf_get_encoding(const struct declaration *field);
 596 int bt_ctf_get_array_len(const struct declaration *field);
 597 uint64_t bt_ctf_get_uint64(const struct definition *field);
 598 int64_t bt_ctf_get_int64(const struct definition *field);
 599 char *bt_ctf_get_char_array(const struct definition *field);
 600 char *bt_ctf_get_string(const struct definition *field);
 601 int bt_ctf_field_get_error(void);
 602 const char *bt_ctf_get_decl_event_name(const struct bt_ctf_event_decl *event);
 603 const char *bt_ctf_get_decl_field_name(const struct bt_ctf_field_decl *field);
 604 const struct declaration *bt_ctf_get_decl_from_def(const struct definition *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(_bt_ctf_get_decl_from_def(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(_bt_ctf_get_decl_from_def(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(_bt_ctf_get_decl_from_def(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(_bt_ctf_get_decl_from_def(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(_bt_ctf_get_decl_from_def(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(_bt_ctf_get_decl_from_def(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 %}