// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.diagnostics.stream;
using zx;

/// A component with records for the Diagnostics system to retrieve.
///
/// To record diagnostics, a component allocates a VMO and begins writing records into the buffer,
/// incrementing a header value after each write to inform readers how much of the buffer has been
/// filled.
///
/// If any retrievers are connected, the `Source` sends them `OnBufferInit` events for each
/// diagnostic buffer created.
///
/// When the buffer fills, the `Source` sends `OnBufferDone` to the retrievers, and will wait for
/// all notified retrievers to reply with `RetireBuffer` when they have finished reading from the
/// buffer.
///
/// When all readers of the buffer have finished, the `Source` may recycle the buffer by zeroing it
/// and sending `OnBufferInit` again to connected retrievers.
///
/// Once a `Source` has sent `OnBufferDone` to a retriever, it is up to the `Source` to handle new
/// records that are generated while the retriever drains the buffer. Double buffering is
/// recommended to prevent excessive blocking, but this protocol does not mandate a specific
/// approach to handling records generated while buffers are full.
[Discoverable]
protocol Source {
    /// Notifies the connected retriever of a new stream buffer. Should be emitted as soon as each
    /// buffer is (re)initialized.
    ///
    /// `latest` should be read-only.
    -> OnBufferInit(zx.handle:VMO latest);

    /// Asks the connected retriever to finish working with `buffer`, usually because the `Source`
    /// does not intend to write further records.
    -> OnBufferDone(zx.koid buffer);

    /// Notifies the `Source` that the retriever is done reading from the buffer. If the `Source`
    /// wishes it should zero the buffer's contents and recycle it for future records. Buffers must
    /// be re-sent via `OnBufferInit` after they're zeroed.
    RetireBuffer(zx.koid buffer);
};