// Copyright 2022 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.
@available(added=11)
library fuchsia.debugdata;

using zx;
using fuchsia.io;

/// Publisher defines the interface for publishing instrumentation data.
@discoverable
closed protocol Publisher {
    /// The program runtime sends a string naming a `data_sink` and transfers
    /// the handle to a VMO containing the `data` it wants published
    /// there.  The `data_sink` string identifies a type of data, and the
    /// VMO's object name can specifically identify the data set in this VMO.
    /// The ZX_PROP_VMO_CONTENT_SIZE property should be set on the VMO to
    /// indicate the precise size of the data in case that is not whole pages;
    /// however, leaving it unset (i.e. 0) is acceptable when the whole-page
    /// size of the VMO is the intended size of dump. Code instrumentation
    /// runtimes use this to deliver large binary trace results. In such cases,
    /// the client can resize the VMO and should use the `vmo_token` handle to
    /// signal when the VMO is ready for processing by the recipient.  The
    /// receiver will not process the VMO until the peer of `vmo_token` handle
    /// is closed. Therefore, the client should retain the peer handle until
    /// it has completed all writes to the VMO.
    strict Publish(resource struct {
        data_sink string:fuchsia.io.MAX_NAME_LENGTH;
        data zx.Handle:VMO;
        vmo_token zx.Handle:EVENTPAIR;
    });
};