// Copyright 2018 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.netemul.sync;

using zx;

/// Simple data structure passed on netemul bus.
type Event = table {
    /// User-defined event code.
    1: code int32;
    /// string:MAX message.
    2: message string:MAX;
    /// serialized arguments.
    3: arguments vector<uint8>:MAX;
};

/// Represents a named bus:
///    a bus is a broadcast pub/sub network that distributes Events.
///    Events are not stored, only forwarded to attached clients.
closed protocol Bus {
    /// Publishes event on the bus.
    strict Publish(struct {
        data Event;
    });
    /// Publishes data on bus and only returns when data has been dispatched.
    /// Use this if you need guarantees that the data was broadcast before continuing.
    /// Note that this ensures that the data will be *published* to all listening clients,
    /// but it cannot guarantee that all clients will have observed the event before it returns.
    strict EnsurePublish(struct {
        data Event;
    }) -> ();
    /// Notifies client of new event.
    strict -> OnBusData(struct {
        data Event;
    });
    /// Get list of named clients.
    strict GetClients() -> (struct {
        clients vector<string:MAX>:MAX;
    });
    /// Notifies a client is now attached.
    /// Upon subscribing to a bus, a client will always receive an `OnClientAttached` event for each
    /// client present on the bus at the moment it joined.
    strict -> OnClientAttached(struct {
        client string:MAX;
    });
    /// Notifies a client was detached.
    strict -> OnClientDetached(struct {
        client string:MAX;
    });
    /// Waits for up to `timeout` (nsec) for all the clients in `clients`.
    /// Returns true if all clients are present on the bus before timeout expired.
    /// If `result` is false, `absent` will contain the entries in `clients` that still weren't
    /// present on the bus when the timout expired.
    /// Use `timeout` <= 0 for indefinite wait.
    strict WaitForClients(struct {
        clients vector<string:MAX>:MAX;
        timeout zx.Duration;
    }) -> (struct {
        result bool;
        absent vector<string:MAX>:<MAX, optional>;
    });
    /// Waits for up to `timeout` (nsec) for an event that matches `data`.
    /// Event equality is performed by comparing *all* set fields in `data`.
    /// Returns true if event was received before timeout expired.
    /// Use `timeout` <= 0 for indefinite wait.
    strict WaitForEvent(struct {
        data Event;
        timeout zx.Duration;
    }) -> (struct {
        result bool;
    });
};

/// The SyncManager is the entry point to attach a client to a bus or use other synchronization
/// primitives.
/// The client's 'ticket' to remain on the bus is the channel obtained through the 'BusSubscribe' call.
@discoverable
closed protocol SyncManager {
    /// Subscribes to bus 'busName' with a given client name.
    /// Duplicate client names are disallowed and will cause the request to return unfulfilled.
    strict BusSubscribe(resource struct {
        bus_name string:MAX;
        client_name string:MAX;
        bus server_end:Bus;
    });
    /// Waits on a named counter barrier with name `barrierName`.
    /// Functon will return true if the number of waits pending on the barrier matches or exceeds
    /// `threshold` before  `timeout` (nsec) expires.
    /// Use `timeout` <= 0 for indefinite wait.
    strict WaitForBarrierThreshold(struct {
        barrier_name string:MAX;
        threshold uint32;
        timeout zx.Duration;
    }) -> (struct {
        result bool;
    });
};