//===--- Tracing.h - Support code for concurrency tracing ----------*- C++ -*-//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
//
//===----------------------------------------------------------------------===//
//
// Support code for tracing events in the concurrency runtime
//
//===----------------------------------------------------------------------===//

#ifndef SWIFT_CONCURRENCY_TRACING_H
#define SWIFT_CONCURRENCY_TRACING_H

#include <stdint.h>

namespace swift {
class AsyncLet;
class AsyncTask;
class ContinuationAsyncContext;
struct HeapObject;
class Job;
class SerialExecutorRef;
class TaskExecutorRef;
class TaskGroup;
class TaskStatusRecord;

namespace concurrency {
namespace trace {

// Actor trace calls.

void actor_create(HeapObject *actor);

void actor_deallocate(HeapObject *actor);

void actor_enqueue(HeapObject *actor, Job *job);

void actor_dequeue(HeapObject *actor, Job *job);

// State values are:
// Idle = 0, Scheduled = 1, Running = 2, Zombie_ReadyForDeallocation = 3,
// invalid/unknown = 255
void actor_state_changed(HeapObject *actor, Job *firstJob, uint8_t state,
                         bool isDistributedRemote, bool isPriorityEscalated,
                         uint8_t maxPriority);

void actor_note_job_queue(HeapObject *actor, Job *first,
                          Job *(*getNext)(Job *));

// Task trace calls.

void task_create(AsyncTask *task, AsyncTask *parent, TaskGroup *group,
                 AsyncLet *asyncLet, uint8_t jobPriority, bool isChildTask,
                 bool isFuture, bool isGroupChildTask, bool isAsyncLetTask,
                 bool isDiscardingTask, bool hasInitialTaskExecutorPreference,
                 const char *taskName);

void task_destroy(AsyncTask *task);

void task_status_changed(AsyncTask *task, uint8_t maxPriority, bool isCancelled,
                         bool isEscalated, bool isStarting, bool isRunning,
                         bool isEnqueued, bool wasRunning);

void task_flags_changed(AsyncTask *task, uint8_t jobPriority, bool isChildTask,
                        bool isFuture, bool isGroupChildTask,
                        bool isAsyncLetTask);

// The `status` parameter is the value of the corresponding
// FutureFragment::Status.
void task_wait(AsyncTask *task, AsyncTask *waitingOn, uintptr_t status);

void task_resume(AsyncTask *task);

// The context parameter is the context pointer used to create the continuation.
// This same pointer will be passed to the corresponding call to
// task_continuation_await and task_continuation_resume.
void task_continuation_init(AsyncTask *task, ContinuationAsyncContext *context);

void task_continuation_await(ContinuationAsyncContext *context);

void task_continuation_resume(ContinuationAsyncContext *context, bool error);

void job_enqueue_global(Job *job);

void job_enqueue_global_with_delay(unsigned long long delay, Job *job);

void job_enqueue_executor(Job *job, SerialExecutorRef serialExecutor,
                          TaskExecutorRef taskExecutor);

enum class TracingExecutorKind : uint8_t {
  GlobalConcurrent,
  DefaultActor,
  MainActor,
  CustomSerialExecutor,
  TaskExecutor,
};

struct job_run_info {
  /// The ID of the task that started running.
  uint64_t taskId;

  /// The signpost ID for this task execution, or OS_SIGNPOST_ID_INVALID
  /// if the job was not a task.
  uint64_t handle;
};

// This returns information that must be passed to the corresponding
// call to task_run_end.  Any information we want to log must be
// extracted from the job when we start to run it because execution
// will invalidate the job.
job_run_info job_run_begin(Job *job, SerialExecutorRef serialExecutor,
                           TaskExecutorRef taskExecutor);

void job_run_end(job_run_info info);

// Emitted when a task switches executors without suspending (i.e., the
// surrounding job_run interval continues, but the active executor has
// changed). Lets trace consumers see executor hops that happen inside a
// single job_run interval.
void task_switch_executor(AsyncTask *task, SerialExecutorRef serialExecutor,
                          TaskExecutorRef taskExecutor);

} // namespace trace
} // namespace concurrency
} // namespace swift

#if SWIFT_STDLIB_TRACING
#include "TracingSignpost.h"
#else
#include "TracingStubs.h"
#endif

#endif
