src/bin/lttng-sessiond/notification-thread.c

   1 /*
   2  * Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * SPDX-License-Identifier: GPL-2.0-only
   5  *
   6  */
   7
   8 #define _LGPL_SOURCE
   9 #include <lttng/trigger/trigger.h>
  10 #include <lttng/notification/channel-internal.h>
  11 #include <lttng/notification/notification-internal.h>
  12 #include <lttng/condition/condition-internal.h>
  13 #include <lttng/condition/buffer-usage-internal.h>
  14 #include <common/error.h>
  15 #include <common/config/session-config.h>
  16 #include <common/defaults.h>
  17 #include <common/utils.h>
  18 #include <common/align.h>
  19 #include <common/time.h>
  20 #include <sys/eventfd.h>
  21 #include <sys/stat.h>
  22 #include <time.h>
  23 #include <signal.h>
  24
  25 #include "notification-thread.h"
  26 #include "notification-thread-events.h"
  27 #include "notification-thread-commands.h"
  28 #include "lttng-sessiond.h"
  29 #include "health-sessiond.h"
  30 #include "thread.h"
  31
  32 #include <urcu.h>
  33 #include <urcu/list.h>
  34 #include <urcu/rculfhash.h>
  35
  36 /*
  37  * Destroy the thread data previously created by the init function.
  38  */
  39 void notification_thread_handle_destroy(
  40                 struct notification_thread_handle *handle)
  41 {
  42         int ret;
  43
  44         if (!handle) {
  45                 goto end;
  46         }
  47
  48         assert(cds_list_empty(&handle->cmd_queue.list));
  49         pthread_mutex_destroy(&handle->cmd_queue.lock);
  50         sem_destroy(&handle->ready);
  51
  52         if (handle->cmd_queue.event_pipe) {
  53                 lttng_pipe_destroy(handle->cmd_queue.event_pipe);
  54         }
  55         if (handle->channel_monitoring_pipes.ust32_consumer >= 0) {
  56                 ret = close(handle->channel_monitoring_pipes.ust32_consumer);
  57                 if (ret) {
  58                         PERROR("close 32-bit consumer channel monitoring pipe");
  59                 }
  60         }
  61         if (handle->channel_monitoring_pipes.ust64_consumer >= 0) {
  62                 ret = close(handle->channel_monitoring_pipes.ust64_consumer);
  63                 if (ret) {
  64                         PERROR("close 64-bit consumer channel monitoring pipe");
  65                 }
  66         }
  67         if (handle->channel_monitoring_pipes.kernel_consumer >= 0) {
  68                 ret = close(handle->channel_monitoring_pipes.kernel_consumer);
  69                 if (ret) {
  70                         PERROR("close kernel consumer channel monitoring pipe");
  71                 }
  72         }
  73 end:
  74         free(handle);
  75 }
  76
  77 struct notification_thread_handle *notification_thread_handle_create(
  78                 struct lttng_pipe *ust32_channel_monitor_pipe,
  79                 struct lttng_pipe *ust64_channel_monitor_pipe,
  80                 struct lttng_pipe *kernel_channel_monitor_pipe)
  81 {
  82         int ret;
  83         struct notification_thread_handle *handle;
  84         struct lttng_pipe *event_pipe = NULL;
  85
  86         handle = zmalloc(sizeof(*handle));
  87         if (!handle) {
  88                 goto end;
  89         }
  90
  91         sem_init(&handle->ready, 0, 0);
  92
  93         event_pipe = lttng_pipe_open(FD_CLOEXEC);
  94         if (!event_pipe) {
  95                 ERR("event_pipe creation");
  96                 goto error;
  97         }
  98
  99         handle->cmd_queue.event_pipe = event_pipe;
 100         event_pipe = NULL;
 101
 102         CDS_INIT_LIST_HEAD(&handle->cmd_queue.list);
 103         ret = pthread_mutex_init(&handle->cmd_queue.lock, NULL);
 104         if (ret) {
 105                 goto error;
 106         }
 107
 108         if (ust32_channel_monitor_pipe) {
 109                 handle->channel_monitoring_pipes.ust32_consumer =
 110                                 lttng_pipe_release_readfd(
 111                                         ust32_channel_monitor_pipe);
 112                 if (handle->channel_monitoring_pipes.ust32_consumer < 0) {
 113                         goto error;
 114                 }
 115         } else {
 116                 handle->channel_monitoring_pipes.ust32_consumer = -1;
 117         }
 118         if (ust64_channel_monitor_pipe) {
 119                 handle->channel_monitoring_pipes.ust64_consumer =
 120                                 lttng_pipe_release_readfd(
 121                                         ust64_channel_monitor_pipe);
 122                 if (handle->channel_monitoring_pipes.ust64_consumer < 0) {
 123                         goto error;
 124                 }
 125         } else {
 126                 handle->channel_monitoring_pipes.ust64_consumer = -1;
 127         }
 128         if (kernel_channel_monitor_pipe) {
 129                 handle->channel_monitoring_pipes.kernel_consumer =
 130                                 lttng_pipe_release_readfd(
 131                                         kernel_channel_monitor_pipe);
 132                 if (handle->channel_monitoring_pipes.kernel_consumer < 0) {
 133                         goto error;
 134                 }
 135         } else {
 136                 handle->channel_monitoring_pipes.kernel_consumer = -1;
 137         }
 138 end:
 139         return handle;
 140 error:
 141         lttng_pipe_destroy(event_pipe);
 142         notification_thread_handle_destroy(handle);
 143         return NULL;
 144 }
 145
 146 static
 147 char *get_notification_channel_sock_path(void)
 148 {
 149         int ret;
 150         bool is_root = !getuid();
 151         char *sock_path;
 152
 153         sock_path = zmalloc(LTTNG_PATH_MAX);
 154         if (!sock_path) {
 155                 goto error;
 156         }
 157
 158         if (is_root) {
 159                 ret = snprintf(sock_path, LTTNG_PATH_MAX,
 160                                 DEFAULT_GLOBAL_NOTIFICATION_CHANNEL_UNIX_SOCK);
 161                 if (ret < 0) {
 162                         goto error;
 163                 }
 164         } else {
 165                 const char *home_path = utils_get_home_dir();
 166
 167                 if (!home_path) {
 168                         ERR("Can't get HOME directory for socket creation");
 169                         goto error;
 170                 }
 171
 172                 ret = snprintf(sock_path, LTTNG_PATH_MAX,
 173                                 DEFAULT_HOME_NOTIFICATION_CHANNEL_UNIX_SOCK,
 174                                 home_path);
 175                 if (ret < 0) {
 176                         goto error;
 177                 }
 178         }
 179
 180         return sock_path;
 181 error:
 182         free(sock_path);
 183         return NULL;
 184 }
 185
 186 static
 187 void notification_channel_socket_destroy(int fd)
 188 {
 189         int ret;
 190         char *sock_path = get_notification_channel_sock_path();
 191
 192         DBG("[notification-thread] Destroying notification channel socket");
 193
 194         if (sock_path) {
 195                 ret = unlink(sock_path);
 196                 free(sock_path);
 197                 if (ret < 0) {
 198                         PERROR("unlink notification channel socket");
 199                 }
 200         }
 201
 202         ret = close(fd);
 203         if (ret) {
 204                 PERROR("close notification channel socket");
 205         }
 206 }
 207
 208 static
 209 int notification_channel_socket_create(void)
 210 {
 211         int fd = -1, ret;
 212         char *sock_path = get_notification_channel_sock_path();
 213
 214         DBG("[notification-thread] Creating notification channel UNIX socket at %s",
 215                         sock_path);
 216
 217         ret = lttcomm_create_unix_sock(sock_path);
 218         if (ret < 0) {
 219                 ERR("[notification-thread] Failed to create notification socket");
 220                 goto error;
 221         }
 222         fd = ret;
 223
 224         ret = chmod(sock_path, S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP);
 225         if (ret < 0) {
 226                 ERR("Set file permissions failed: %s", sock_path);
 227                 PERROR("chmod notification channel socket");
 228                 goto error;
 229         }
 230
 231         if (getuid() == 0) {
 232                 gid_t gid;
 233
 234                 ret =  utils_get_group_id(config.tracing_group_name.value, true,
 235                                 &gid);
 236                 if (ret) {
 237                         /* Default to root group. */
 238                         gid = 0;
 239                 }
 240
 241                 ret = chown(sock_path, 0, gid);
 242                 if (ret) {
 243                         ERR("Failed to set the notification channel socket's group");
 244                         ret = -1;
 245                         goto error;
 246                 }
 247         }
 248
 249         DBG("[notification-thread] Notification channel UNIX socket created (fd = %i)",
 250                         fd);
 251         free(sock_path);
 252         return fd;
 253 error:
 254         if (fd >= 0 && close(fd) < 0) {
 255                 PERROR("close notification channel socket");
 256         }
 257         free(sock_path);
 258         return ret;
 259 }
 260
 261 static
 262 int init_poll_set(struct lttng_poll_event *poll_set,
 263                 struct notification_thread_handle *handle,
 264                 int notification_channel_socket)
 265 {
 266         int ret;
 267
 268         /*
 269          * Create pollset with size 5:
 270          *      - notification channel socket (listen for new connections),
 271          *      - command queue event fd (internal sessiond commands),
 272          *      - consumerd (32-bit user space) channel monitor pipe,
 273          *      - consumerd (64-bit user space) channel monitor pipe,
 274          *      - consumerd (kernel) channel monitor pipe.
 275          */
 276         ret = lttng_poll_create(poll_set, 5, LTTNG_CLOEXEC);
 277         if (ret < 0) {
 278                 goto end;
 279         }
 280
 281         ret = lttng_poll_add(poll_set, notification_channel_socket,
 282                         LPOLLIN | LPOLLERR | LPOLLHUP | LPOLLRDHUP);
 283         if (ret < 0) {
 284                 ERR("[notification-thread] Failed to add notification channel socket to pollset");
 285                 goto error;
 286         }
 287         ret = lttng_poll_add(poll_set, lttng_pipe_get_readfd(handle->cmd_queue.event_pipe),
 288                         LPOLLIN | LPOLLERR);
 289         if (ret < 0) {
 290                 ERR("[notification-thread] Failed to add notification command queue event fd to pollset");
 291                 goto error;
 292         }
 293         ret = lttng_poll_add(poll_set,
 294                         handle->channel_monitoring_pipes.ust32_consumer,
 295                         LPOLLIN | LPOLLERR);
 296         if (ret < 0) {
 297                 ERR("[notification-thread] Failed to add ust-32 channel monitoring pipe fd to pollset");
 298                 goto error;
 299         }
 300         ret = lttng_poll_add(poll_set,
 301                         handle->channel_monitoring_pipes.ust64_consumer,
 302                         LPOLLIN | LPOLLERR);
 303         if (ret < 0) {
 304                 ERR("[notification-thread] Failed to add ust-64 channel monitoring pipe fd to pollset");
 305                 goto error;
 306         }
 307         if (handle->channel_monitoring_pipes.kernel_consumer < 0) {
 308                 goto end;
 309         }
 310         ret = lttng_poll_add(poll_set,
 311                         handle->channel_monitoring_pipes.kernel_consumer,
 312                         LPOLLIN | LPOLLERR);
 313         if (ret < 0) {
 314                 ERR("[notification-thread] Failed to add kernel channel monitoring pipe fd to pollset");
 315                 goto error;
 316         }
 317 end:
 318         return ret;
 319 error:
 320         lttng_poll_clean(poll_set);
 321         return ret;
 322 }
 323
 324 static
 325 void fini_thread_state(struct notification_thread_state *state)
 326 {
 327         int ret;
 328
 329         if (state->client_socket_ht) {
 330                 ret = handle_notification_thread_client_disconnect_all(state);
 331                 assert(!ret);
 332                 ret = cds_lfht_destroy(state->client_socket_ht, NULL);
 333                 assert(!ret);
 334         }
 335         if (state->client_id_ht) {
 336                 ret = cds_lfht_destroy(state->client_id_ht, NULL);
 337                 assert(!ret);
 338         }
 339         if (state->triggers_ht) {
 340                 ret = handle_notification_thread_trigger_unregister_all(state);
 341                 assert(!ret);
 342                 ret = cds_lfht_destroy(state->triggers_ht, NULL);
 343                 assert(!ret);
 344         }
 345         if (state->channel_triggers_ht) {
 346                 ret = cds_lfht_destroy(state->channel_triggers_ht, NULL);
 347                 assert(!ret);
 348         }
 349         if (state->channel_state_ht) {
 350                 ret = cds_lfht_destroy(state->channel_state_ht, NULL);
 351                 assert(!ret);
 352         }
 353         if (state->notification_trigger_clients_ht) {
 354                 ret = cds_lfht_destroy(state->notification_trigger_clients_ht,
 355                                 NULL);
 356                 assert(!ret);
 357         }
 358         if (state->channels_ht) {
 359                 ret = cds_lfht_destroy(state->channels_ht, NULL);
 360                 assert(!ret);
 361         }
 362         if (state->sessions_ht) {
 363                 ret = cds_lfht_destroy(state->sessions_ht, NULL);
 364                 assert(!ret);
 365         }
 366         /*
 367          * Must be destroyed after all channels have been destroyed.
 368          * See comment in struct lttng_session_trigger_list.
 369          */
 370         if (state->session_triggers_ht) {
 371                 ret = cds_lfht_destroy(state->session_triggers_ht, NULL);
 372                 assert(!ret);
 373         }
 374         if (state->notification_channel_socket >= 0) {
 375                 notification_channel_socket_destroy(
 376                                 state->notification_channel_socket);
 377         }
 378         if (state->executor) {
 379                 action_executor_destroy(state->executor);
 380         }
 381         lttng_poll_clean(&state->events);
 382 }
 383
 384 static
 385 void mark_thread_as_ready(struct notification_thread_handle *handle)
 386 {
 387         DBG("Marking notification thread as ready");
 388         sem_post(&handle->ready);
 389 }
 390
 391 static
 392 void wait_until_thread_is_ready(struct notification_thread_handle *handle)
 393 {
 394         DBG("Waiting for notification thread to be ready");
 395         sem_wait(&handle->ready);
 396         DBG("Notification thread is ready");
 397 }
 398
 399 static
 400 int init_thread_state(struct notification_thread_handle *handle,
 401                 struct notification_thread_state *state)
 402 {
 403         int ret;
 404
 405         memset(state, 0, sizeof(*state));
 406         state->notification_channel_socket = -1;
 407         lttng_poll_init(&state->events);
 408
 409         ret = notification_channel_socket_create();
 410         if (ret < 0) {
 411                 goto end;
 412         }
 413         state->notification_channel_socket = ret;
 414
 415         ret = init_poll_set(&state->events, handle,
 416                         state->notification_channel_socket);
 417         if (ret) {
 418                 goto end;
 419         }
 420
 421         DBG("[notification-thread] Listening on notification channel socket");
 422         ret = lttcomm_listen_unix_sock(state->notification_channel_socket);
 423         if (ret < 0) {
 424                 ERR("[notification-thread] Listen failed on notification channel socket");
 425                 goto error;
 426         }
 427
 428         state->client_socket_ht = cds_lfht_new(DEFAULT_HT_SIZE, 1, 0,
 429                         CDS_LFHT_AUTO_RESIZE | CDS_LFHT_ACCOUNTING, NULL);
 430         if (!state->client_socket_ht) {
 431                 goto error;
 432         }
 433
 434         state->client_id_ht = cds_lfht_new(DEFAULT_HT_SIZE, 1, 0,
 435                         CDS_LFHT_AUTO_RESIZE | CDS_LFHT_ACCOUNTING, NULL);
 436         if (!state->client_id_ht) {
 437                 goto error;
 438         }
 439
 440         state->channel_triggers_ht = cds_lfht_new(DEFAULT_HT_SIZE, 1, 0,
 441                         CDS_LFHT_AUTO_RESIZE | CDS_LFHT_ACCOUNTING, NULL);
 442         if (!state->channel_triggers_ht) {
 443                 goto error;
 444         }
 445
 446         state->session_triggers_ht = cds_lfht_new(DEFAULT_HT_SIZE, 1, 0,
 447                         CDS_LFHT_AUTO_RESIZE | CDS_LFHT_ACCOUNTING, NULL);
 448         if (!state->session_triggers_ht) {
 449                 goto error;
 450         }
 451
 452         state->channel_state_ht = cds_lfht_new(DEFAULT_HT_SIZE, 1, 0,
 453                         CDS_LFHT_AUTO_RESIZE | CDS_LFHT_ACCOUNTING, NULL);
 454         if (!state->channel_state_ht) {
 455                 goto error;
 456         }
 457
 458         state->notification_trigger_clients_ht = cds_lfht_new(DEFAULT_HT_SIZE,
 459                         1, 0, CDS_LFHT_AUTO_RESIZE | CDS_LFHT_ACCOUNTING, NULL);
 460         if (!state->notification_trigger_clients_ht) {
 461                 goto error;
 462         }
 463
 464         state->channels_ht = cds_lfht_new(DEFAULT_HT_SIZE,
 465                         1, 0, CDS_LFHT_AUTO_RESIZE | CDS_LFHT_ACCOUNTING, NULL);
 466         if (!state->channels_ht) {
 467                 goto error;
 468         }
 469         state->sessions_ht = cds_lfht_new(DEFAULT_HT_SIZE,
 470                         1, 0, CDS_LFHT_AUTO_RESIZE | CDS_LFHT_ACCOUNTING, NULL);
 471         if (!state->sessions_ht) {
 472                 goto error;
 473         }
 474         state->triggers_ht = cds_lfht_new(DEFAULT_HT_SIZE,
 475                         1, 0, CDS_LFHT_AUTO_RESIZE | CDS_LFHT_ACCOUNTING, NULL);
 476         if (!state->triggers_ht) {
 477                 goto error;
 478         }
 479
 480         state->executor = action_executor_create(handle);
 481         if (!state->executor) {
 482                 goto error;
 483         }
 484         mark_thread_as_ready(handle);
 485 end:
 486         return 0;
 487 error:
 488         fini_thread_state(state);
 489         return -1;
 490 }
 491
 492 static
 493 int handle_channel_monitoring_pipe(int fd, uint32_t revents,
 494                 struct notification_thread_handle *handle,
 495                 struct notification_thread_state *state)
 496 {
 497         int ret = 0;
 498         enum lttng_domain_type domain;
 499
 500         if (fd == handle->channel_monitoring_pipes.ust32_consumer ||
 501                         fd == handle->channel_monitoring_pipes.ust64_consumer) {
 502                 domain = LTTNG_DOMAIN_UST;
 503         } else if (fd == handle->channel_monitoring_pipes.kernel_consumer) {
 504                 domain = LTTNG_DOMAIN_KERNEL;
 505         } else {
 506                 abort();
 507         }
 508
 509         if (revents & (LPOLLERR | LPOLLHUP | LPOLLRDHUP)) {
 510                 ret = lttng_poll_del(&state->events, fd);
 511                 if (ret) {
 512                         ERR("[notification-thread] Failed to remove consumer monitoring pipe from poll set");
 513                 }
 514                 goto end;
 515         }
 516
 517         ret = handle_notification_thread_channel_sample(
 518                         state, fd, domain);
 519         if (ret) {
 520                 ERR("[notification-thread] Consumer sample handling error occurred");
 521                 ret = -1;
 522                 goto end;
 523         }
 524 end:
 525         return ret;
 526 }
 527
 528 /*
 529  * This thread services notification channel clients and commands received
 530  * from various lttng-sessiond components over a command queue.
 531  */
 532 static
 533 void *thread_notification(void *data)
 534 {
 535         int ret;
 536         struct notification_thread_handle *handle = data;
 537         struct notification_thread_state state;
 538
 539         DBG("[notification-thread] Started notification thread");
 540
 541         health_register(health_sessiond, HEALTH_SESSIOND_TYPE_NOTIFICATION);
 542         rcu_register_thread();
 543         rcu_thread_online();
 544
 545         if (!handle) {
 546                 ERR("[notification-thread] Invalid thread context provided");
 547                 goto end;
 548         }
 549
 550         health_code_update();
 551
 552         ret = init_thread_state(handle, &state);
 553         if (ret) {
 554                 goto end;
 555         }
 556
 557         while (true) {
 558                 int fd_count, i;
 559
 560                 health_poll_entry();
 561                 DBG("[notification-thread] Entering poll wait");
 562                 ret = lttng_poll_wait(&state.events, -1);
 563                 DBG("[notification-thread] Poll wait returned (%i)", ret);
 564                 health_poll_exit();
 565                 if (ret < 0) {
 566                         /*
 567                          * Restart interrupted system call.
 568                          */
 569                         if (errno == EINTR) {
 570                                 continue;
 571                         }
 572                         ERR("[notification-thread] Error encountered during lttng_poll_wait (%i)", ret);
 573                         goto error;
 574                 }
 575
 576                 fd_count = ret;
 577                 for (i = 0; i < fd_count; i++) {
 578                         int fd = LTTNG_POLL_GETFD(&state.events, i);
 579                         uint32_t revents = LTTNG_POLL_GETEV(&state.events, i);
 580
 581                         DBG("[notification-thread] Handling fd (%i) activity (%u)", fd, revents);
 582
 583                         if (fd == state.notification_channel_socket) {
 584                                 if (revents & LPOLLIN) {
 585                                         ret = handle_notification_thread_client_connect(
 586                                                         &state);
 587                                         if (ret < 0) {
 588                                                 goto error;
 589                                         }
 590                                 } else if (revents &
 591                                                 (LPOLLERR | LPOLLHUP | LPOLLRDHUP)) {
 592                                         ERR("[notification-thread] Notification socket poll error");
 593                                         goto error;
 594                                 } else {
 595                                         ERR("[notification-thread] Unexpected poll events %u for notification socket %i", revents, fd);
 596                                         goto error;
 597                                 }
 598                         } else if (fd == lttng_pipe_get_readfd(handle->cmd_queue.event_pipe)) {
 599                                 ret = handle_notification_thread_command(handle,
 600                                                 &state);
 601                                 if (ret < 0) {
 602                                         DBG("[notification-thread] Error encountered while servicing command queue");
 603                                         goto error;
 604                                 } else if (ret > 0) {
 605                                         goto exit;
 606                                 }
 607                         } else if (fd == handle->channel_monitoring_pipes.ust32_consumer ||
 608                                         fd == handle->channel_monitoring_pipes.ust64_consumer ||
 609                                         fd == handle->channel_monitoring_pipes.kernel_consumer) {
 610                                 ret = handle_channel_monitoring_pipe(fd,
 611                                                 revents, handle, &state);
 612                                 if (ret) {
 613                                         goto error;
 614                                 }
 615                         } else {
 616                                 /* Activity on a client's socket. */
 617                                 if (revents & (LPOLLERR | LPOLLHUP | LPOLLRDHUP)) {
 618                                         /*
 619                                          * It doesn't matter if a command was
 620                                          * pending on the client socket at this
 621                                          * point since it now has no way to
 622                                          * receive the notifications to which
 623                                          * it was subscribing or unsubscribing.
 624                                          */
 625                                         ret = handle_notification_thread_client_disconnect(
 626                                                         fd, &state);
 627                                         if (ret) {
 628                                                 goto error;
 629                                         }
 630                                 } else {
 631                                         if (revents & LPOLLIN) {
 632                                                 ret = handle_notification_thread_client_in(
 633                                                         &state, fd);
 634                                                 if (ret) {
 635                                                         goto error;
 636                                                 }
 637                                         }
 638
 639                                         if (revents & LPOLLOUT) {
 640                                                 ret = handle_notification_thread_client_out(
 641                                                         &state, fd);
 642                                                 if (ret) {
 643                                                         goto error;
 644                                                 }
 645                                         }
 646                                 }
 647                         }
 648                 }
 649         }
 650 exit:
 651 error:
 652         fini_thread_state(&state);
 653 end:
 654         rcu_thread_offline();
 655         rcu_unregister_thread();
 656         health_unregister(health_sessiond);
 657         return NULL;
 658 }
 659
 660 static
 661 bool shutdown_notification_thread(void *thread_data)
 662 {
 663         struct notification_thread_handle *handle = thread_data;
 664
 665         notification_thread_command_quit(handle);
 666         return true;
 667 }
 668
 669 struct lttng_thread *launch_notification_thread(
 670                 struct notification_thread_handle *handle)
 671 {
 672         struct lttng_thread *thread;
 673
 674         thread = lttng_thread_create("Notification",
 675                         thread_notification,
 676                         shutdown_notification_thread,
 677                         NULL,
 678                         handle);
 679         if (!thread) {
 680                 goto error;
 681         }
 682
 683         /*
 684          * Wait for the thread to be marked as "ready" before returning
 685          * as other subsystems depend on the notification subsystem
 686          * (e.g. rotation thread).
 687          */
 688         wait_until_thread_is_ready(handle);
 689         return thread;
 690 error:
 691         return NULL;
 692 }