lib/ctf-ir/stream-class.c

   1 /*
   2  * stream-class.c
   3  *
   4  * Babeltrace CTF IR - Stream Class
   5  *
   6  * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   7  *
   8  * Author: Jérémie Galarneau <jeremie.galarneau@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  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  21  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  23  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  24  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  25  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  26  * SOFTWARE.
  27  */
  28
  29 #define BT_LOG_TAG "STREAM-CLASS"
  30 #include <babeltrace/lib-logging-internal.h>
  31
  32 #include <babeltrace/ctf-writer/clock.h>
  33 #include <babeltrace/ctf-writer/clock-internal.h>
  34 #include <babeltrace/ctf-ir/clock-class-internal.h>
  35 #include <babeltrace/ctf-writer/event.h>
  36 #include <babeltrace/ctf-ir/event-class-internal.h>
  37 #include <babeltrace/ctf-ir/event-internal.h>
  38 #include <babeltrace/ctf-ir/field-types-internal.h>
  39 #include <babeltrace/ctf-ir/fields-internal.h>
  40 #include <babeltrace/ctf-writer/stream.h>
  41 #include <babeltrace/ctf-ir/stream-class-internal.h>
  42 #include <babeltrace/ctf-ir/validation-internal.h>
  43 #include <babeltrace/ctf-ir/visitor-internal.h>
  44 #include <babeltrace/ctf-writer/functor-internal.h>
  45 #include <babeltrace/ctf-ir/utils.h>
  46 #include <babeltrace/ref.h>
  47 #include <babeltrace/compiler-internal.h>
  48 #include <babeltrace/align-internal.h>
  49 #include <babeltrace/endian-internal.h>
  50 #include <inttypes.h>
  51 #include <stdint.h>
  52 #include <stdbool.h>
  53
  54 static
  55 void bt_stream_class_destroy(struct bt_object *obj);
  56 static
  57 int init_event_header(struct bt_stream_class *stream_class);
  58 static
  59 int init_packet_context(struct bt_stream_class *stream_class);
  60
  61 struct bt_stream_class *bt_stream_class_create(const char *name)
  62 {
  63         struct bt_stream_class *stream_class;
  64         int ret;
  65
  66         BT_LOGD("Creating default stream class object: name=\"%s\"", name);
  67         stream_class = bt_stream_class_create_empty(name);
  68         if (!stream_class) {
  69                 BT_LOGD_STR("Cannot create empty stream class.");
  70                 goto error;
  71         }
  72
  73         ret = init_event_header(stream_class);
  74         if (ret) {
  75                 BT_LOGE_STR("Cannot initialize stream class's event header field type.");
  76                 goto error;
  77         }
  78
  79         ret = init_packet_context(stream_class);
  80         if (ret) {
  81                 BT_LOGE_STR("Cannot initialize stream class's packet context field type.");
  82                 goto error;
  83         }
  84
  85         BT_LOGD("Created default stream class object: addr=%p, name=\"%s\"",
  86                 stream_class, name);
  87         return stream_class;
  88
  89 error:
  90         BT_PUT(stream_class);
  91         return stream_class;
  92 }
  93
  94 struct bt_stream_class *bt_stream_class_create_empty(const char *name)
  95 {
  96         struct bt_stream_class *stream_class = NULL;
  97
  98         BT_LOGD("Creating empty stream class object: name=\"%s\"", name);
  99
 100         stream_class = g_new0(struct bt_stream_class, 1);
 101         if (!stream_class) {
 102                 BT_LOGE_STR("Failed to allocate one stream class.");
 103                 goto error;
 104         }
 105
 106         stream_class->name = g_string_new(name);
 107         stream_class->event_classes = g_ptr_array_new_with_free_func(
 108                 (GDestroyNotify) bt_object_release);
 109         if (!stream_class->event_classes) {
 110                 BT_LOGE_STR("Failed to allocate a GPtrArray.");
 111                 goto error;
 112         }
 113
 114         stream_class->event_classes_ht = g_hash_table_new_full(g_int64_hash,
 115                         g_int64_equal, g_free, NULL);
 116         if (!stream_class->event_classes_ht) {
 117                 BT_LOGE_STR("Failed to allocate a GHashTable.");
 118                 goto error;
 119         }
 120
 121         bt_object_init(stream_class, bt_stream_class_destroy);
 122         BT_LOGD("Created empty stream class object: addr=%p, name=\"%s\"",
 123                 stream_class, name);
 124         return stream_class;
 125
 126 error:
 127         BT_PUT(stream_class);
 128         return stream_class;
 129 }
 130
 131 struct bt_trace *bt_stream_class_get_trace(
 132                 struct bt_stream_class *stream_class)
 133 {
 134         return stream_class ?
 135                 bt_get(bt_stream_class_borrow_trace(stream_class)) :
 136                 NULL;
 137 }
 138
 139 const char *bt_stream_class_get_name(
 140                 struct bt_stream_class *stream_class)
 141 {
 142         const char *name = NULL;
 143
 144         if (!stream_class) {
 145                 BT_LOGW_STR("Invalid parameter: stream class is NULL.");
 146                 goto end;
 147         }
 148
 149         name = stream_class->name->len > 0 ? stream_class->name->str : NULL;
 150 end:
 151         return name;
 152 }
 153
 154 int bt_stream_class_set_name(struct bt_stream_class *stream_class,
 155                 const char *name)
 156 {
 157         int ret = 0;
 158
 159         if (!stream_class) {
 160                 BT_LOGW_STR("Invalid parameter: stream class is NULL.");
 161                 ret = -1;
 162                 goto end;
 163         }
 164
 165         if (stream_class->frozen) {
 166                 BT_LOGW("Invalid parameter: stream class is frozen: "
 167                         "addr=%p, name=\"%s\", id=%" PRId64,
 168                         stream_class, bt_stream_class_get_name(stream_class),
 169                         bt_stream_class_get_id(stream_class));
 170                 ret = -1;
 171                 goto end;
 172         }
 173
 174         if (!name) {
 175                 g_string_assign(stream_class->name, "");
 176         } else {
 177                 if (strlen(name) == 0) {
 178                         BT_LOGW("Invalid parameter: name is empty.");
 179                         ret = -1;
 180                         goto end;
 181                 }
 182
 183                 g_string_assign(stream_class->name, name);
 184         }
 185
 186         BT_LOGV("Set stream class's name: "
 187                 "addr=%p, name=\"%s\", id=%" PRId64,
 188                 stream_class, bt_stream_class_get_name(stream_class),
 189                 bt_stream_class_get_id(stream_class));
 190 end:
 191         return ret;
 192 }
 193
 194 struct bt_ctf_clock *bt_stream_class_get_clock(
 195                 struct bt_stream_class *stream_class)
 196 {
 197         struct bt_ctf_clock *clock = NULL;
 198
 199         if (!stream_class) {
 200                 BT_LOGW_STR("Invalid parameter: stream class is NULL.");
 201                 goto end;
 202         }
 203
 204         if (!stream_class->clock) {
 205                 BT_LOGV("Stream class has no clock: "
 206                         "addr=%p, name=\"%s\", id=%" PRId64,
 207                         stream_class, bt_stream_class_get_name(stream_class),
 208                         bt_stream_class_get_id(stream_class));
 209                 goto end;
 210         }
 211
 212         clock = bt_get(stream_class->clock);
 213 end:
 214         return clock;
 215 }
 216
 217 int bt_stream_class_set_clock(struct bt_stream_class *stream_class,
 218                 struct bt_ctf_clock *clock)
 219 {
 220         int ret = 0;
 221         struct bt_field_type *timestamp_field = NULL;
 222
 223         if (!stream_class || !clock) {
 224                 BT_LOGW("Invalid parameter: stream class or clock is NULL: "
 225                         "stream-class-addr=%p, clock-addr=%p",
 226                         stream_class, clock);
 227                 ret = -1;
 228                 goto end;
 229         }
 230
 231         if (stream_class->frozen) {
 232                 BT_LOGW("Invalid parameter: stream class is frozen: "
 233                         "addr=%p, name=\"%s\", id=%" PRId64,
 234                         stream_class, bt_stream_class_get_name(stream_class),
 235                         bt_stream_class_get_id(stream_class));
 236                 ret = -1;
 237                 goto end;
 238         }
 239
 240         /* Replace the current clock of this stream class. */
 241         bt_put(stream_class->clock);
 242         stream_class->clock = bt_get(clock);
 243         BT_LOGV("Set stream class's clock: "
 244                 "addr=%p, name=\"%s\", id=%" PRId64 ", "
 245                 "clock-addr=%p, clock-name=\"%s\"",
 246                 stream_class, bt_stream_class_get_name(stream_class),
 247                 bt_stream_class_get_id(stream_class),
 248                 stream_class->clock,
 249                 bt_ctf_clock_get_name(stream_class->clock));
 250
 251 end:
 252         bt_put(timestamp_field);
 253         return ret;
 254 }
 255
 256 int64_t bt_stream_class_get_id(struct bt_stream_class *stream_class)
 257 {
 258         int64_t ret;
 259
 260         if (!stream_class) {
 261                 BT_LOGW_STR("Invalid parameter: stream class is NULL.");
 262                 ret = (int64_t) -1;
 263                 goto end;
 264         }
 265
 266         if (!stream_class->id_set) {
 267                 BT_LOGV("Stream class's ID is not set: addr=%p, name=\"%s\"",
 268                         stream_class,
 269                         bt_stream_class_get_name(stream_class));
 270                 ret = (int64_t) -1;
 271                 goto end;
 272         }
 273
 274         ret = stream_class->id;
 275 end:
 276         return ret;
 277 }
 278
 279 BT_HIDDEN
 280 void _bt_stream_class_set_id(
 281                 struct bt_stream_class *stream_class, int64_t id)
 282 {
 283         assert(stream_class);
 284         stream_class->id = id;
 285         stream_class->id_set = 1;
 286         BT_LOGV("Set stream class's ID (internal): "
 287                 "addr=%p, name=\"%s\", id=%" PRId64,
 288                 stream_class, bt_stream_class_get_name(stream_class),
 289                 bt_stream_class_get_id(stream_class));
 290 }
 291
 292 struct event_class_set_stream_class_id_data {
 293         int64_t stream_class_id;
 294         int ret;
 295 };
 296
 297 BT_HIDDEN
 298 int bt_stream_class_set_id_no_check(
 299                 struct bt_stream_class *stream_class, int64_t id)
 300 {
 301         _bt_stream_class_set_id(stream_class, id);
 302         return 0;
 303 }
 304
 305 int bt_stream_class_set_id(struct bt_stream_class *stream_class,
 306                 uint64_t id_param)
 307 {
 308         int ret = 0;
 309         int64_t id = (int64_t) id_param;
 310
 311         if (!stream_class) {
 312                 BT_LOGW_STR("Invalid parameter: stream class is NULL.");
 313                 ret = -1;
 314                 goto end;
 315         }
 316
 317         if (stream_class->frozen) {
 318                 BT_LOGW("Invalid parameter: stream class is frozen: "
 319                         "addr=%p, name=\"%s\", id=%" PRId64,
 320                         stream_class, bt_stream_class_get_name(stream_class),
 321                         bt_stream_class_get_id(stream_class));
 322                 ret = -1;
 323                 goto end;
 324         }
 325
 326         if (id < 0) {
 327                 BT_LOGW("Invalid parameter: invalid stream class's ID: "
 328                         "stream-class-addr=%p, stream-class-name=\"%s\", "
 329                         "stream-class-id=%" PRId64 ", id=%" PRIu64,
 330                         stream_class, bt_stream_class_get_name(stream_class),
 331                         bt_stream_class_get_id(stream_class),
 332                         id_param);
 333                 ret = -1;
 334                 goto end;
 335         }
 336
 337         ret = bt_stream_class_set_id_no_check(stream_class, id);
 338         if (ret == 0) {
 339                 BT_LOGV("Set stream class's ID: "
 340                         "addr=%p, name=\"%s\", id=%" PRId64,
 341                         stream_class, bt_stream_class_get_name(stream_class),
 342                         bt_stream_class_get_id(stream_class));
 343         }
 344 end:
 345         return ret;
 346 }
 347
 348 static
 349 void event_class_exists(gpointer element, gpointer query)
 350 {
 351         struct bt_event_class *event_class_a = element;
 352         struct search_query *search_query = query;
 353         struct bt_event_class *event_class_b = search_query->value;
 354         int64_t id_a, id_b;
 355
 356         if (search_query->value == element) {
 357                 search_query->found = 1;
 358                 goto end;
 359         }
 360
 361         /*
 362          * Two event classes cannot share the same ID in a given
 363          * stream class.
 364          */
 365         id_a = bt_event_class_get_id(event_class_a);
 366         id_b = bt_event_class_get_id(event_class_b);
 367
 368         if (id_a < 0 || id_b < 0) {
 369                 /* at least one ID is not set: will be automatically set later */
 370                 goto end;
 371         }
 372
 373         if (id_a == id_b) {
 374                 BT_LOGW("Event class with this ID already exists in the stream class: "
 375                         "id=%" PRId64 ", name=\"%s\"",
 376                         id_a, bt_event_class_get_name(event_class_a));
 377                 search_query->found = 1;
 378                 goto end;
 379         }
 380
 381 end:
 382         return;
 383 }
 384
 385 int bt_stream_class_add_event_class(
 386                 struct bt_stream_class *stream_class,
 387                 struct bt_event_class *event_class)
 388 {
 389         int ret = 0;
 390         int64_t *event_id = NULL;
 391         struct bt_trace *trace = NULL;
 392         struct bt_stream_class *old_stream_class = NULL;
 393         struct bt_validation_output validation_output = { 0 };
 394         struct bt_field_type *packet_header_type = NULL;
 395         struct bt_field_type *packet_context_type = NULL;
 396         struct bt_field_type *event_header_type = NULL;
 397         struct bt_field_type *stream_event_ctx_type = NULL;
 398         struct bt_field_type *event_context_type = NULL;
 399         struct bt_field_type *event_payload_type = NULL;
 400         const enum bt_validation_flag validation_flags =
 401                 BT_VALIDATION_FLAG_EVENT;
 402
 403         if (!stream_class || !event_class) {
 404                 BT_LOGW("Invalid parameter: stream class or event class is NULL: "
 405                         "stream-class-addr=%p, event-class-addr=%p",
 406                         stream_class, event_class);
 407                 ret = -1;
 408                 goto end;
 409         }
 410
 411         BT_LOGD("Adding event class to stream class: "
 412                 "stream-class-addr=%p, stream-class-name=\"%s\", "
 413                 "stream-class-id=%" PRId64 ", event-class-addr=%p, "
 414                 "event-class-name=\"%s\", event-class-id=%" PRId64,
 415                 stream_class, bt_stream_class_get_name(stream_class),
 416                 bt_stream_class_get_id(stream_class),
 417                 event_class,
 418                 bt_event_class_get_name(event_class),
 419                 bt_event_class_get_id(event_class));
 420
 421         trace = bt_stream_class_get_trace(stream_class);
 422         if (trace && trace->is_static) {
 423                 ret = -1;
 424                 goto end;
 425         }
 426
 427         event_id = g_new(int64_t, 1);
 428         if (!event_id) {
 429                 BT_LOGE_STR("Failed to allocate one int64_t.");
 430                 ret = -1;
 431                 goto end;
 432         }
 433
 434         /* Check for duplicate event classes */
 435         struct search_query query = { .value = event_class, .found = 0 };
 436         g_ptr_array_foreach(stream_class->event_classes, event_class_exists,
 437                 &query);
 438         if (query.found) {
 439                 BT_LOGW_STR("Another event class part of this stream class has the same ID.");
 440                 ret = -1;
 441                 goto end;
 442         }
 443
 444         old_stream_class = bt_event_class_get_stream_class(event_class);
 445         if (old_stream_class) {
 446                 /* Event class is already associated to a stream class. */
 447                 BT_LOGW("Event class is already part of another stream class: "
 448                         "event-class-stream-class-addr=%p, "
 449                         "event-class-stream-class-name=\"%s\", "
 450                         "event-class-stream-class-id=%" PRId64,
 451                         old_stream_class,
 452                         bt_stream_class_get_name(old_stream_class),
 453                         bt_stream_class_get_id(old_stream_class));
 454                 ret = -1;
 455                 goto end;
 456         }
 457
 458         if (trace) {
 459                 /*
 460                  * If the stream class is associated with a trace, then
 461                  * both those objects are frozen. Also, this event class
 462                  * is about to be frozen.
 463                  *
 464                  * Therefore the event class must be validated here.
 465                  * The trace and stream class should be valid at this
 466                  * point.
 467                  */
 468                 assert(trace->valid);
 469                 assert(stream_class->valid);
 470                 packet_header_type =
 471                         bt_trace_get_packet_header_type(trace);
 472                 packet_context_type =
 473                         bt_stream_class_get_packet_context_type(
 474                                 stream_class);
 475                 event_header_type =
 476                         bt_stream_class_get_event_header_type(stream_class);
 477                 stream_event_ctx_type =
 478                         bt_stream_class_get_event_context_type(
 479                                 stream_class);
 480                 event_context_type =
 481                         bt_event_class_get_context_type(event_class);
 482                 event_payload_type =
 483                         bt_event_class_get_payload_type(event_class);
 484                 ret = bt_validate_class_types(
 485                         trace->environment, packet_header_type,
 486                         packet_context_type, event_header_type,
 487                         stream_event_ctx_type, event_context_type,
 488                         event_payload_type, trace->valid,
 489                         stream_class->valid, event_class->valid,
 490                         &validation_output, validation_flags);
 491                 BT_PUT(packet_header_type);
 492                 BT_PUT(packet_context_type);
 493                 BT_PUT(event_header_type);
 494                 BT_PUT(stream_event_ctx_type);
 495                 BT_PUT(event_context_type);
 496                 BT_PUT(event_payload_type);
 497
 498                 if (ret) {
 499                         /*
 500                          * This means something went wrong during the
 501                          * validation process, not that the objects are
 502                          * invalid.
 503                          */
 504                         BT_LOGE("Failed to validate event class: ret=%d", ret);
 505                         goto end;
 506                 }
 507
 508                 if ((validation_output.valid_flags & validation_flags) !=
 509                                 validation_flags) {
 510                         /* Invalid event class */
 511                         BT_LOGW("Invalid trace, stream class, or event class: "
 512                                 "valid-flags=0x%x",
 513                                 validation_output.valid_flags);
 514                         ret = -1;
 515                         goto end;
 516                 }
 517         }
 518
 519         /* Only set an event ID if none was explicitly set before */
 520         *event_id = bt_event_class_get_id(event_class);
 521         if (*event_id < 0) {
 522                 BT_LOGV("Event class has no ID: automatically setting it: "
 523                         "id=%" PRId64, stream_class->next_event_id);
 524
 525                 if (bt_event_class_set_id(event_class,
 526                                 stream_class->next_event_id)) {
 527                         BT_LOGE("Cannot set event class's ID: id=%" PRId64,
 528                                 stream_class->next_event_id);
 529                         ret = -1;
 530                         goto end;
 531                 }
 532                 stream_class->next_event_id++;
 533                 *event_id = stream_class->next_event_id;
 534         }
 535
 536         bt_object_set_parent(event_class, stream_class);
 537
 538         if (trace) {
 539                 /*
 540                  * At this point we know that the function will be
 541                  * successful. Therefore we can replace the event
 542                  * class's field types with what's in the validation
 543                  * output structure and mark this event class as valid.
 544                  */
 545                 bt_validation_replace_types(NULL, NULL, event_class,
 546                         &validation_output, validation_flags);
 547                 event_class->valid = 1;
 548
 549                 /*
 550                  * Put what was not moved in
 551                  * bt_validation_replace_types().
 552                  */
 553                 bt_validation_output_put_types(&validation_output);
 554         }
 555
 556         /* Add to the event classes of the stream class */
 557         g_ptr_array_add(stream_class->event_classes, event_class);
 558         g_hash_table_insert(stream_class->event_classes_ht, event_id,
 559                         event_class);
 560         event_id = NULL;
 561
 562         /* Freeze the event class */
 563         bt_event_class_freeze(event_class);
 564
 565         /* Notifiy listeners of the trace's schema modification. */
 566         if (trace) {
 567                 struct bt_visitor_object obj = { .object = event_class,
 568                                 .type = BT_VISITOR_OBJECT_TYPE_EVENT_CLASS };
 569
 570                 (void) bt_trace_object_modification(&obj, trace);
 571         }
 572
 573         BT_LOGD("Added event class to stream class: "
 574                 "stream-class-addr=%p, stream-class-name=\"%s\", "
 575                 "stream-class-id=%" PRId64 ", event-class-addr=%p, "
 576                 "event-class-name=\"%s\", event-class-id=%" PRId64,
 577                 stream_class, bt_stream_class_get_name(stream_class),
 578                 bt_stream_class_get_id(stream_class),
 579                 event_class,
 580                 bt_event_class_get_name(event_class),
 581                 bt_event_class_get_id(event_class));
 582
 583 end:
 584         BT_PUT(trace);
 585         BT_PUT(old_stream_class);
 586         bt_validation_output_put_types(&validation_output);
 587         assert(!packet_header_type);
 588         assert(!packet_context_type);
 589         assert(!event_header_type);
 590         assert(!stream_event_ctx_type);
 591         assert(!event_context_type);
 592         assert(!event_payload_type);
 593         g_free(event_id);
 594
 595         return ret;
 596 }
 597
 598 int64_t bt_stream_class_get_event_class_count(
 599                 struct bt_stream_class *stream_class)
 600 {
 601         int64_t ret;
 602
 603         if (!stream_class) {
 604                 BT_LOGW_STR("Invalid parameter: stream class is NULL.");
 605                 ret = (int64_t) -1;
 606                 goto end;
 607         }
 608
 609         ret = (int64_t) stream_class->event_classes->len;
 610 end:
 611         return ret;
 612 }
 613
 614 struct bt_event_class *bt_stream_class_get_event_class_by_index(
 615                 struct bt_stream_class *stream_class, uint64_t index)
 616 {
 617         struct bt_event_class *event_class = NULL;
 618
 619         if (!stream_class) {
 620                 BT_LOGW_STR("Invalid parameter: stream class is NULL.");
 621                 goto end;
 622         }
 623
 624         if (index >= stream_class->event_classes->len) {
 625                 BT_LOGW("Invalid parameter: index is out of bounds: "
 626                         "addr=%p, name=\"%s\", id=%" PRId64 ", "
 627                         "index=%" PRIu64 ", count=%u",
 628                         stream_class, bt_stream_class_get_name(stream_class),
 629                         bt_stream_class_get_id(stream_class),
 630                         index, stream_class->event_classes->len);
 631                 goto end;
 632         }
 633
 634         event_class = g_ptr_array_index(stream_class->event_classes, index);
 635         bt_get(event_class);
 636 end:
 637         return event_class;
 638 }
 639
 640 struct bt_event_class *bt_stream_class_get_event_class_by_id(
 641                 struct bt_stream_class *stream_class, uint64_t id)
 642 {
 643         int64_t id_key = (int64_t) id;
 644         struct bt_event_class *event_class = NULL;
 645
 646         if (!stream_class) {
 647                 BT_LOGW_STR("Invalid parameter: stream class is NULL.");
 648                 goto end;
 649         }
 650
 651         if (id_key < 0) {
 652                 BT_LOGW("Invalid parameter: invalid event class's ID: "
 653                         "stream-class-addr=%p, stream-class-name=\"%s\", "
 654                         "stream-class-id=%" PRId64 ", event-class-id=%" PRIu64,
 655                         stream_class,
 656                         bt_stream_class_get_name(stream_class),
 657                         bt_stream_class_get_id(stream_class), id);
 658                 goto end;
 659         }
 660
 661         event_class = g_hash_table_lookup(stream_class->event_classes_ht,
 662                         &id_key);
 663         bt_get(event_class);
 664 end:
 665         return event_class;
 666 }
 667
 668 struct bt_field_type *bt_stream_class_get_packet_context_type(
 669                 struct bt_stream_class *stream_class)
 670 {
 671         struct bt_field_type *ret = NULL;
 672
 673         if (!stream_class) {
 674                 BT_LOGW_STR("Invalid parameter: stream class is NULL.");
 675                 goto end;
 676         }
 677
 678         bt_get(stream_class->packet_context_type);
 679         ret = stream_class->packet_context_type;
 680 end:
 681         return ret;
 682 }
 683
 684 int bt_stream_class_set_packet_context_type(
 685                 struct bt_stream_class *stream_class,
 686                 struct bt_field_type *packet_context_type)
 687 {
 688         int ret = 0;
 689
 690         if (!stream_class) {
 691                 BT_LOGW_STR("Invalid parameter: stream class is NULL.");
 692                 ret = -1;
 693                 goto end;
 694         }
 695
 696         if (stream_class->frozen) {
 697                 BT_LOGW("Invalid parameter: stream class is frozen: "
 698                         "addr=%p, name=\"%s\", id=%" PRId64,
 699                         stream_class, bt_stream_class_get_name(stream_class),
 700                         bt_stream_class_get_id(stream_class));
 701                 ret = -1;
 702                 goto end;
 703         }
 704
 705         if (packet_context_type &&
 706                         bt_field_type_get_type_id(packet_context_type) !=
 707                                 BT_FIELD_TYPE_ID_STRUCT) {
 708                 /* A packet context must be a structure. */
 709                 BT_LOGW("Invalid parameter: stream class's packet context field type must be a structure: "
 710                         "addr=%p, name=\"%s\", id=%" PRId64 ", "
 711                         "packet-context-ft-addr=%p, packet-context-ft-id=%s",
 712                         stream_class, bt_stream_class_get_name(stream_class),
 713                         bt_stream_class_get_id(stream_class),
 714                         packet_context_type,
 715                         bt_field_type_id_string(
 716                                 bt_field_type_get_type_id(packet_context_type)));
 717                 ret = -1;
 718                 goto end;
 719         }
 720
 721         bt_put(stream_class->packet_context_type);
 722         bt_get(packet_context_type);
 723         stream_class->packet_context_type = packet_context_type;
 724         BT_LOGV("Set stream class's packet context field type: "
 725                 "addr=%p, name=\"%s\", id=%" PRId64 ", "
 726                 "packet-context-ft-addr=%p",
 727                 stream_class, bt_stream_class_get_name(stream_class),
 728                 bt_stream_class_get_id(stream_class),
 729                 packet_context_type);
 730
 731 end:
 732         return ret;
 733 }
 734
 735 struct bt_field_type *bt_stream_class_get_event_header_type(
 736                 struct bt_stream_class *stream_class)
 737 {
 738         struct bt_field_type *ret = NULL;
 739
 740         if (!stream_class) {
 741                 BT_LOGW_STR("Invalid parameter: stream class is NULL.");
 742                 goto end;
 743         }
 744
 745         if (!stream_class->event_header_type) {
 746                 BT_LOGV("Stream class has no event header field type: "
 747                         "addr=%p, name=\"%s\", id=%" PRId64,
 748                         stream_class, bt_stream_class_get_name(stream_class),
 749                         bt_stream_class_get_id(stream_class));
 750                 goto end;
 751         }
 752
 753         bt_get(stream_class->event_header_type);
 754         ret = stream_class->event_header_type;
 755 end:
 756         return ret;
 757 }
 758
 759 int bt_stream_class_set_event_header_type(
 760                 struct bt_stream_class *stream_class,
 761                 struct bt_field_type *event_header_type)
 762 {
 763         int ret = 0;
 764
 765         if (!stream_class) {
 766                 BT_LOGW_STR("Invalid parameter: stream class is NULL.");
 767                 ret = -1;
 768                 goto end;
 769         }
 770
 771         if (stream_class->frozen) {
 772                 BT_LOGW("Invalid parameter: stream class is frozen: "
 773                         "addr=%p, name=\"%s\", id=%" PRId64,
 774                         stream_class, bt_stream_class_get_name(stream_class),
 775                         bt_stream_class_get_id(stream_class));
 776                 ret = -1;
 777                 goto end;
 778         }
 779
 780         if (event_header_type &&
 781                         bt_field_type_get_type_id(event_header_type) !=
 782                                 BT_FIELD_TYPE_ID_STRUCT) {
 783                 /* An event header must be a structure. */
 784                 BT_LOGW("Invalid parameter: stream class's event header field type must be a structure: "
 785                         "addr=%p, name=\"%s\", id=%" PRId64 ", "
 786                         "event-header-ft-addr=%p, event-header-ft-id=%s",
 787                         stream_class, bt_stream_class_get_name(stream_class),
 788                         bt_stream_class_get_id(stream_class),
 789                         event_header_type,
 790                         bt_field_type_id_string(
 791                                 bt_field_type_get_type_id(event_header_type)));
 792                 ret = -1;
 793                 goto end;
 794         }
 795
 796         bt_put(stream_class->event_header_type);
 797         stream_class->event_header_type = bt_get(event_header_type);
 798         BT_LOGV("Set stream class's event header field type: "
 799                 "addr=%p, name=\"%s\", id=%" PRId64 ", "
 800                 "event-header-ft-addr=%p",
 801                 stream_class, bt_stream_class_get_name(stream_class),
 802                 bt_stream_class_get_id(stream_class),
 803                 event_header_type);
 804 end:
 805         return ret;
 806 }
 807
 808 struct bt_field_type *bt_stream_class_get_event_context_type(
 809                 struct bt_stream_class *stream_class)
 810 {
 811         struct bt_field_type *ret = NULL;
 812
 813         if (!stream_class) {
 814                 BT_LOGW_STR("Invalid parameter: stream class is NULL.");
 815                 goto end;
 816         }
 817
 818         if (!stream_class->event_context_type) {
 819                 goto end;
 820         }
 821
 822         bt_get(stream_class->event_context_type);
 823         ret = stream_class->event_context_type;
 824 end:
 825         return ret;
 826 }
 827
 828 int bt_stream_class_set_event_context_type(
 829                 struct bt_stream_class *stream_class,
 830                 struct bt_field_type *event_context_type)
 831 {
 832         int ret = 0;
 833
 834         if (!stream_class) {
 835                 BT_LOGW_STR("Invalid parameter: stream class is NULL.");
 836                 ret = -1;
 837                 goto end;
 838         }
 839
 840         if (stream_class->frozen) {
 841                 BT_LOGW("Invalid parameter: stream class is frozen: "
 842                         "addr=%p, name=\"%s\", id=%" PRId64,
 843                         stream_class, bt_stream_class_get_name(stream_class),
 844                         bt_stream_class_get_id(stream_class));
 845                 ret = -1;
 846                 goto end;
 847         }
 848
 849         if (event_context_type &&
 850                         bt_field_type_get_type_id(event_context_type) !=
 851                                 BT_FIELD_TYPE_ID_STRUCT) {
 852                 /* A packet context must be a structure. */
 853                 BT_LOGW("Invalid parameter: stream class's event context field type must be a structure: "
 854                         "addr=%p, name=\"%s\", id=%" PRId64 ", "
 855                         "event-context-ft-addr=%p, event-context-ft-id=%s",
 856                         stream_class, bt_stream_class_get_name(stream_class),
 857                         bt_stream_class_get_id(stream_class),
 858                         event_context_type,
 859                         bt_field_type_id_string(
 860                                 bt_field_type_get_type_id(event_context_type)));
 861                 ret = -1;
 862                 goto end;
 863         }
 864
 865         bt_put(stream_class->event_context_type);
 866         stream_class->event_context_type = bt_get(event_context_type);
 867         BT_LOGV("Set stream class's event context field type: "
 868                 "addr=%p, name=\"%s\", id=%" PRId64 ", "
 869                 "event-context-ft-addr=%p",
 870                 stream_class, bt_stream_class_get_name(stream_class),
 871                 bt_stream_class_get_id(stream_class),
 872                 event_context_type);
 873 end:
 874         return ret;
 875 }
 876
 877 /* Pre-2.0 CTF writer backward compatibility */
 878 void bt_ctf_stream_class_get(struct bt_stream_class *stream_class)
 879 {
 880         bt_get(stream_class);
 881 }
 882
 883 /* Pre-2.0 CTF writer backward compatibility */
 884 void bt_ctf_stream_class_put(struct bt_stream_class *stream_class)
 885 {
 886         bt_put(stream_class);
 887 }
 888
 889 static
 890 int64_t get_event_class_count(void *element)
 891 {
 892         return bt_stream_class_get_event_class_count(
 893                         (struct bt_stream_class *) element);
 894 }
 895
 896 static
 897 void *get_event_class(void *element, int i)
 898 {
 899         return bt_stream_class_get_event_class_by_index(
 900                         (struct bt_stream_class *) element, i);
 901 }
 902
 903 static
 904 int visit_event_class(void *object, bt_visitor visitor,void *data)
 905 {
 906         struct bt_visitor_object obj =
 907                         { .object = object,
 908                         .type = BT_VISITOR_OBJECT_TYPE_EVENT_CLASS };
 909
 910         return visitor(&obj, data);
 911 }
 912
 913 int bt_stream_class_visit(struct bt_stream_class *stream_class,
 914                 bt_visitor visitor, void *data)
 915 {
 916         int ret;
 917         struct bt_visitor_object obj =
 918                         { .object = stream_class,
 919                         .type = BT_VISITOR_OBJECT_TYPE_STREAM_CLASS };
 920
 921         if (!stream_class || !visitor) {
 922                 BT_LOGW("Invalid parameter: stream class or visitor is NULL: "
 923                         "stream-class-addr=%p, visitor=%p",
 924                         stream_class, visitor);
 925                 ret = -1;
 926                 goto end;
 927         }
 928
 929         ret = visitor_helper(&obj, get_event_class_count,
 930                         get_event_class,
 931                         visit_event_class, visitor, data);
 932         BT_LOGV("visitor_helper() returned: ret=%d", ret);
 933 end:
 934         return ret;
 935 }
 936
 937 BT_HIDDEN
 938 void bt_stream_class_freeze(struct bt_stream_class *stream_class)
 939 {
 940         if (!stream_class || stream_class->frozen) {
 941                 return;
 942         }
 943
 944         BT_LOGD("Freezing stream class: addr=%p, name=\"%s\", id=%" PRId64,
 945                 stream_class, bt_stream_class_get_name(stream_class),
 946                 bt_stream_class_get_id(stream_class));
 947         stream_class->frozen = 1;
 948         bt_field_type_freeze(stream_class->event_header_type);
 949         bt_field_type_freeze(stream_class->packet_context_type);
 950         bt_field_type_freeze(stream_class->event_context_type);
 951
 952         if (stream_class->clock) {
 953                 bt_clock_class_freeze(stream_class->clock->clock_class);
 954         }
 955 }
 956
 957 BT_HIDDEN
 958 int bt_stream_class_serialize(struct bt_stream_class *stream_class,
 959                 struct metadata_context *context)
 960 {
 961         int ret = 0;
 962         size_t i;
 963         struct bt_trace *trace;
 964         struct bt_field_type *packet_header_type = NULL;
 965
 966         BT_LOGD("Serializing stream class's metadata: "
 967                 "stream-class-addr=%p, stream-class-name=\"%s\", "
 968                 "stream-class-id=%" PRId64 ", metadata-context-addr=%p",
 969                 stream_class, bt_stream_class_get_name(stream_class),
 970                 bt_stream_class_get_id(stream_class), context);
 971         g_string_assign(context->field_name, "");
 972         context->current_indentation_level = 1;
 973         if (!stream_class->id_set) {
 974                 BT_LOGW_STR("Stream class's ID is not set.");
 975                 ret = -1;
 976                 goto end;
 977         }
 978
 979         g_string_append(context->string, "stream {\n");
 980
 981         /*
 982          * The reference to the trace is only borrowed since the
 983          * serialization of the stream class might have been triggered
 984          * by the trace's destruction. In such a case, the trace's
 985          * reference count would, unexepectedly, go through the sequence
 986          * 1 -> 0 -> 1 -> 0 -> ..., provoking an endless loop of destruction
 987          * and serialization.
 988          */
 989         trace = bt_stream_class_borrow_trace(stream_class);
 990         assert(trace);
 991         packet_header_type = bt_trace_get_packet_header_type(trace);
 992         trace = NULL;
 993         if (packet_header_type) {
 994                 struct bt_field_type *stream_id_type;
 995
 996                 stream_id_type =
 997                         bt_field_type_structure_get_field_type_by_name(
 998                                 packet_header_type, "stream_id");
 999                 if (stream_id_type) {
1000                         /*
1001                          * Only set the stream's id if the trace's packet header
1002                          * contains a stream_id field. This field is only
1003                          * needed if the trace contains only one stream
1004                          * class.
1005                          */
1006                         g_string_append_printf(context->string,
1007                                 "\tid = %" PRId64 ";\n", stream_class->id);
1008                 }
1009                 bt_put(stream_id_type);
1010         }
1011         if (stream_class->event_header_type) {
1012                 BT_LOGD_STR("Serializing stream class's event header field type's metadata.");
1013                 g_string_append(context->string, "\tevent.header := ");
1014                 ret = bt_field_type_serialize(stream_class->event_header_type,
1015                         context);
1016                 if (ret) {
1017                         BT_LOGW("Cannot serialize stream class's event header field type's metadata: "
1018                                 "ret=%d", ret);
1019                         goto end;
1020                 }
1021                 g_string_append(context->string, ";");
1022         }
1023
1024
1025         if (stream_class->packet_context_type) {
1026                 BT_LOGD_STR("Serializing stream class's packet context field type's metadata.");
1027                 g_string_append(context->string, "\n\n\tpacket.context := ");
1028                 ret = bt_field_type_serialize(stream_class->packet_context_type,
1029                         context);
1030                 if (ret) {
1031                         BT_LOGW("Cannot serialize stream class's packet context field type's metadata: "
1032                                 "ret=%d", ret);
1033                         goto end;
1034                 }
1035                 g_string_append(context->string, ";");
1036         }
1037
1038         if (stream_class->event_context_type) {
1039                 BT_LOGD_STR("Serializing stream class's event context field type's metadata.");
1040                 g_string_append(context->string, "\n\n\tevent.context := ");
1041                 ret = bt_field_type_serialize(
1042                         stream_class->event_context_type, context);
1043                 if (ret) {
1044                         BT_LOGW("Cannot serialize stream class's event context field type's metadata: "
1045                                 "ret=%d", ret);
1046                         goto end;
1047                 }
1048                 g_string_append(context->string, ";");
1049         }
1050
1051         g_string_append(context->string, "\n};\n\n");
1052
1053         for (i = 0; i < stream_class->event_classes->len; i++) {
1054                 struct bt_event_class *event_class =
1055                         stream_class->event_classes->pdata[i];
1056
1057                 ret = bt_event_class_serialize(event_class, context);
1058                 if (ret) {
1059                         BT_LOGW("Cannot serialize event class's metadata: "
1060                                 "event-class-addr=%p, event-class-name=\"%s\", "
1061                                 "event-class-id=%" PRId64,
1062                                 event_class,
1063                                 bt_event_class_get_name(event_class),
1064                                 bt_event_class_get_id(event_class));
1065                         goto end;
1066                 }
1067         }
1068 end:
1069         bt_put(packet_header_type);
1070         context->current_indentation_level = 0;
1071         return ret;
1072 }
1073
1074 static
1075 void bt_stream_class_destroy(struct bt_object *obj)
1076 {
1077         struct bt_stream_class *stream_class;
1078
1079         stream_class = container_of(obj, struct bt_stream_class, base);
1080         BT_LOGD("Destroying stream class: addr=%p, name=\"%s\", id=%" PRId64,
1081                 stream_class, bt_stream_class_get_name(stream_class),
1082                 bt_stream_class_get_id(stream_class));
1083         bt_put(stream_class->clock);
1084
1085         if (stream_class->event_classes_ht) {
1086                 g_hash_table_destroy(stream_class->event_classes_ht);
1087         }
1088         if (stream_class->event_classes) {
1089                 BT_LOGD_STR("Destroying event classes.");
1090                 g_ptr_array_free(stream_class->event_classes, TRUE);
1091         }
1092
1093         if (stream_class->name) {
1094                 g_string_free(stream_class->name, TRUE);
1095         }
1096
1097         BT_LOGD_STR("Putting event header field type.");
1098         bt_put(stream_class->event_header_type);
1099         BT_LOGD_STR("Putting packet context field type.");
1100         bt_put(stream_class->packet_context_type);
1101         BT_LOGD_STR("Putting event context field type.");
1102         bt_put(stream_class->event_context_type);
1103         g_free(stream_class);
1104 }
1105
1106 static
1107 int init_event_header(struct bt_stream_class *stream_class)
1108 {
1109         int ret = 0;
1110         struct bt_field_type *event_header_type =
1111                 bt_field_type_structure_create();
1112         struct bt_field_type *_uint32_t =
1113                 get_field_type(FIELD_TYPE_ALIAS_UINT32_T);
1114         struct bt_field_type *_uint64_t =
1115                 get_field_type(FIELD_TYPE_ALIAS_UINT64_T);
1116
1117         if (!event_header_type) {
1118                 BT_LOGE_STR("Cannot create empty structure field type.");
1119                 ret = -1;
1120                 goto end;
1121         }
1122
1123         ret = bt_field_type_structure_add_field(event_header_type,
1124                 _uint32_t, "id");
1125         if (ret) {
1126                 BT_LOGE_STR("Cannot add `id` field to event header field type.");
1127                 goto end;
1128         }
1129
1130         ret = bt_field_type_structure_add_field(event_header_type,
1131                 _uint64_t, "timestamp");
1132         if (ret) {
1133                 BT_LOGE_STR("Cannot add `timestamp` field to event header field type.");
1134                 goto end;
1135         }
1136
1137         BT_MOVE(stream_class->event_header_type, event_header_type);
1138 end:
1139         if (ret) {
1140                 bt_put(event_header_type);
1141         }
1142
1143         bt_put(_uint32_t);
1144         bt_put(_uint64_t);
1145         return ret;
1146 }
1147
1148 static
1149 int init_packet_context(struct bt_stream_class *stream_class)
1150 {
1151         int ret = 0;
1152         struct bt_field_type *packet_context_type =
1153                 bt_field_type_structure_create();
1154         struct bt_field_type *_uint64_t =
1155                 get_field_type(FIELD_TYPE_ALIAS_UINT64_T);
1156         struct bt_field_type *ts_begin_end_uint64_t;
1157
1158         if (!packet_context_type) {
1159                 BT_LOGE_STR("Cannot create empty structure field type.");
1160                 ret = -1;
1161                 goto end;
1162         }
1163
1164         ts_begin_end_uint64_t = bt_field_type_copy(_uint64_t);
1165         if (!ts_begin_end_uint64_t) {
1166                 BT_LOGE_STR("Cannot copy integer field type for `timestamp_begin` and `timestamp_end` fields.");
1167                 ret = -1;
1168                 goto end;
1169         }
1170
1171         /*
1172          * We create a stream packet context as proposed in the CTF
1173          * specification.
1174          */
1175         ret = bt_field_type_structure_add_field(packet_context_type,
1176                 ts_begin_end_uint64_t, "timestamp_begin");
1177         if (ret) {
1178                 BT_LOGE_STR("Cannot add `timestamp_begin` field to event header field type.");
1179                 goto end;
1180         }
1181
1182         ret = bt_field_type_structure_add_field(packet_context_type,
1183                 ts_begin_end_uint64_t, "timestamp_end");
1184         if (ret) {
1185                 BT_LOGE_STR("Cannot add `timestamp_end` field to event header field type.");
1186                 goto end;
1187         }
1188
1189         ret = bt_field_type_structure_add_field(packet_context_type,
1190                 _uint64_t, "content_size");
1191         if (ret) {
1192                 BT_LOGE_STR("Cannot add `content_size` field to event header field type.");
1193                 goto end;
1194         }
1195
1196         ret = bt_field_type_structure_add_field(packet_context_type,
1197                 _uint64_t, "packet_size");
1198         if (ret) {
1199                 BT_LOGE_STR("Cannot add `packet_size` field to event header field type.");
1200                 goto end;
1201         }
1202
1203         ret = bt_field_type_structure_add_field(packet_context_type,
1204                 _uint64_t, "events_discarded");
1205         if (ret) {
1206                 BT_LOGE_STR("Cannot add `events_discarded` field to event header field type.");
1207                 goto end;
1208         }
1209
1210         BT_MOVE(stream_class->packet_context_type, packet_context_type);
1211 end:
1212         if (ret) {
1213                 bt_put(packet_context_type);
1214                 goto end;
1215         }
1216
1217         bt_put(_uint64_t);
1218         bt_put(ts_begin_end_uint64_t);
1219         return ret;
1220 }
1221
1222 static
1223 int try_map_clock_class(struct bt_stream_class *stream_class,
1224                 struct bt_field_type *ft)
1225 {
1226         struct bt_clock_class *mapped_clock_class = NULL;
1227         int ret = 0;
1228
1229         if (!ft) {
1230                 /* Field does not exist: not an error */
1231                 goto end;
1232         }
1233
1234         assert(bt_field_type_is_integer(ft));
1235         mapped_clock_class =
1236                 bt_field_type_integer_get_mapped_clock_class(ft);
1237         if (!mapped_clock_class) {
1238                 if (!stream_class->clock) {
1239                         BT_LOGW("Cannot automatically set field's type mapped clock class: stream class's clock is not set: "
1240                                 "stream-class-addr=%p, stream-class-name=\"%s\", "
1241                                 "stream-class-id=%" PRId64 ", ft-addr=%p",
1242                                 stream_class, bt_stream_class_get_name(stream_class),
1243                                 bt_stream_class_get_id(stream_class), ft);
1244                         ret = -1;
1245                         goto end;
1246                 }
1247
1248                 ret = bt_field_type_integer_set_mapped_clock_class_no_check(
1249                         ft, stream_class->clock->clock_class);
1250                 if (ret) {
1251                         BT_LOGW("Cannot set field type's mapped clock class: "
1252                                 "stream-class-addr=%p, stream-class-name=\"%s\", "
1253                                 "stream-class-id=%" PRId64 ", ft-addr=%p",
1254                                 stream_class, bt_stream_class_get_name(stream_class),
1255                                 bt_stream_class_get_id(stream_class), ft);
1256                         goto end;
1257                 }
1258
1259                 BT_LOGV("Automatically mapped field type to stream class's clock class: "
1260                         "stream-class-addr=%p, stream-class-name=\"%s\", "
1261                         "stream-class-id=%" PRId64 ", ft-addr=%p",
1262                         stream_class, bt_stream_class_get_name(stream_class),
1263                         bt_stream_class_get_id(stream_class), ft);
1264         }
1265
1266 end:
1267         bt_put(mapped_clock_class);
1268         return ret;
1269 }
1270
1271 BT_HIDDEN
1272 int bt_stream_class_map_clock_class(
1273                 struct bt_stream_class *stream_class,
1274                 struct bt_field_type *packet_context_type,
1275                 struct bt_field_type *event_header_type)
1276 {
1277         struct bt_field_type *ft = NULL;
1278         int ret = 0;
1279
1280         assert(stream_class);
1281
1282         if (packet_context_type) {
1283                 ft = bt_field_type_structure_get_field_type_by_name(
1284                         packet_context_type, "timestamp_begin");
1285                 if (try_map_clock_class(stream_class, ft)) {
1286                         BT_LOGE_STR("Cannot automatically set stream class's packet context field type's `timestamp_begin` field's mapped clock class.");
1287                         ret = -1;
1288                         goto end;
1289                 }
1290
1291                 bt_put(ft);
1292                 ft = bt_field_type_structure_get_field_type_by_name(
1293                         packet_context_type, "timestamp_end");
1294                 if (try_map_clock_class(stream_class, ft)) {
1295                         BT_LOGE_STR("Cannot automatically set stream class's packet context field type's `timestamp_end` field's mapped clock class.");
1296                         ret = -1;
1297                         goto end;
1298                 }
1299
1300                 BT_PUT(ft);
1301         }
1302
1303         if (event_header_type) {
1304                 ft = bt_field_type_structure_get_field_type_by_name(
1305                         event_header_type, "timestamp");
1306                 if (try_map_clock_class(stream_class, ft)) {
1307                         BT_LOGE_STR("Cannot automatically set stream class's event header field type's `timestamp` field's mapped clock class.");
1308                         ret = -1;
1309                         goto end;
1310                 }
1311
1312                 BT_PUT(ft);
1313         }
1314
1315 end:
1316         return ret;
1317 }