// 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.net.neighbor;

/// Options for modifying the behavior of an [`EntryIterator`].
table EntryIteratorOptions {
    // Reserved for future expansions, like filtering per-interface.
};

/// Returns entries and events from the neighbor table. Clients can open an
/// iterator using the [`fuchsia.net.neighbor/View.EntryIterator`] method.
///
/// An atomic snapshot of the neighbor table is queued for clients upon opening
/// an EntryIterator. This snapshot consists of `existing` entries followed by
/// an [`IdleEvent`]. No other types of events will be sent before an
/// [`IdleEvent`].
protocol EntryIterator {
    /// Take items from the iterator. If no items are available, block until one
    /// is; otherwise, return immediately with items queued since the last
    /// invocation.
    ///
    /// This does not guarantee that, when blocking, only one item will be
    /// returned; implementations may debounce or batch events.
    ///
    /// Attempt to maintain one in-flight `GetNext` call as much as possible.
    /// If `GetNext` is not constantly polled, the networking stack might hit an
    /// upper limit on the number of buffered events, resulting in dropping.
    /// Should this happen, this connection will be closed with a
    /// `ZX_ERR_IO_OVERRUN` epitaph.
    ///
    /// If there is more than one in-flight `GetNext` call, callers are put into
    /// a queue and will receive responses in FIFO order.
    ///
    /// - response `events` a list of events that occurred since the last
    ///     invocation of this method.
    GetNext() -> (vector<EntryIteratorItem>:MAX_ITEM_BATCH_SIZE events);
};

/// Items returned from [`EntryIterator.GetNext`].
union EntryIteratorItem {
    /// An existing entry in the neighbor table. Does not indicate that an event
    /// occurred.
    1: Entry existing;

    /// Event indicating the iterator will no longer return `existing` items.
    2: IdleEvent idle;

    /// Event indicating an entry has been added into the neighbor table.
    3: Entry added;

    /// Event indicating an entry has changed.
    4: Entry changed;

    /// Event indicating an entry has been removed from the neighbor table.
    5: Entry removed;
};

/// Empty event for indicating there are no more [`EntryIteratorItem.existing`]
/// items to yield.
struct IdleEvent {
};

/// The maximum number of [`EntryIteratorItem`] returned in a
/// [`EntryIterator.GetNext`] response.
//
// This has been calculated with the following function:
//   MAX_EVENT_BATCH_SIZE = floor_pow2(
//     (ZX_CHANNEL_MAX_MSG_BYTES - RESPONSE_BYTES) / MAX_EVENT_BYTES
//   )
// where,
//   ZX_CHANNEL_MAX_MSG_BYTES = 65536 bytes
//   RESPONSE_BYTES = size of [`EntryIterator.GetNext`] response = 32 bytes
//   MAX_ITEM_BYTES = max size of [`EntryIteratorItem`] = 208 bytes
//
// It's rounded down to the next power of two for aesthetics and decreased
// sensitivity to changes to the underlying data structures.
// This value will need to be recomputed if any of the above numbers change.
const uint64 MAX_ITEM_BATCH_SIZE = 256;