syntax = "proto3";

package rs.tokio.console.async_ops;

import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
import "common.proto";


// An `AsyncOp` state update.
//
// This includes a list of any new async ops, and updates to the associated statistics
// for any async ops that have changed since the last update.
message AsyncOpUpdate {
    // A list of new async operations that were created since the last `AsyncOpUpdate`
    // was sent. Note that the fact that an async operation has been created
    // does not mean that is has been polled or is being polled. This information
    // is reflected in the `Stats` of the operation.
    repeated AsyncOp new_async_ops = 1;
    // Any async op stats that have changed since the last update.
    map<uint64, Stats> stats_update = 2;
    // A count of how many async op events (e.g. polls, creation, etc) were not
    // recorded because the application's event buffer was at capacity.
    //
    // If everything is working normally, this should be 0. If it is greater
    // than 0, that may indicate that some data is missing from this update, and
    // it may be necessary to increase the number of events buffered by the
    // application to ensure that data loss is avoided.
    //
    // If the application's instrumentation ensures reliable delivery of events,
    // this will always be 0.
    uint64 dropped_events = 3;
}

// An async operation.
//
// An async operation is an operation that is associated with a resource
// This could, for example, be a read or write on a TCP stream, or a receive operation on
// a channel.
message AsyncOp {
    // The async op's ID.
    //
    // This uniquely identifies this op across all *currently live*
    // ones.
    common.Id id = 1;
    // The numeric ID of the op's `Metadata`.
    //
    // This identifies the `Metadata` that describes the `tracing` span
    // corresponding to this async op. The metadata for this ID will have been sent
    // in a prior `RegisterMetadata` message.
    common.MetaId metadata = 2;
    // The source of this async operation. Most commonly this should be the name
    // of the method where the instantiation of this op has happened.
    string source = 3;
    // The ID of the parent async op.
    //
    // This field is only set if this async op was created while inside of another
    // async op.  For example, `tokio::sync`'s `Mutex::lock` internally calls
    // `Semaphore::acquire`.
    //
    // This field can be empty; if it is empty, this async op is not a child of another
    // async op.
    common.Id parent_async_op_id = 4;
    // The resources's ID.
    common.Id resource_id = 5;
}

// Statistics associated with a given async operation.
message Stats {
    // Timestamp of when the async op has been created.
    google.protobuf.Timestamp created_at = 1;
    // Timestamp of when the async op was dropped.
    google.protobuf.Timestamp dropped_at = 2;
    // The Id of the task that is awaiting on this op.
    common.Id task_id = 4;
    // Contains the operation poll stats.
    common.PollStats poll_stats = 5;
    // State attributes of the async op.
    repeated common.Attribute attributes = 6;
}