// Copyright 2017 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.modular;

using fuchsia.mem;

// A message queue is a named, locally persistent FIFO data structure. Message
// queues are created, read from, and deleted by component instances through
// their ComponentContext service.
//
// A message queue is created by a component instance from its component context
// in order to receive messages in it.
//
// A sender token that identifies the queue can be obtained from the message
// queue connection and passed to other components. This enables the other
// component to send messages to the queue. A sender token does not allow a
// component to read messages from a queue.
//
// The name of a queue is local to the component instance, i.e. it can only be
// used by the component instance that created the queue to access it. The name
// can specifically be used to obtain a MessageReader connection for the message
// queue.
//
// The existence of message queues and their tokens is synchronized across
// devices, allowing components with instances on multiple devices to route
// messages within each device. For example, modules can use sender tokens on
// different devices and see those messages delivered to the agent instance on
// the same device. However, individual messages are local to a device.
protocol MessageQueue {
    // Gets a sender token associated with this queue. It can be used by other
    // components to send messages to this queue.
    GetToken() -> (string queue_token);

    // Registers a receiver for this MessageQueue. MessageReader.OnReceive() is
    // called when there is an unread message. There can be at most one receiver
    // registered for a message queue at any time. Registering a new receiver
    // replaces the previous one.
    RegisterReceiver(MessageReader receiver);
};

// Used to send a message to a message queue. The MessageSender connection is
// obtained from ComponentContext.GetMessageSender() using a queue token of the
// MessageQueue. The queue token is obtained by the component that created the
// message queue and is then passed to the other component through services
// specific to either component.
protocol MessageSender {
    Send(fuchsia.mem.Buffer message);
};

// A component instance may implement and register a MessageReader interface
// using MessageQueue.RegisterReceiver(). When there are new unread messages,
// they are sent to MessageReader.OnReceive(). TODO(vardhan): There is a
// conflict with C++ fidl bindings for 'MessageReceiver'. After that is fixed,
// rename this interface to MessageReceiver.
protocol MessageReader {
    // Called when there is a new message to be received. Once an OnReceive()
    // responds back, the message is acknowledged as having been received and the
    // next one is sent when available. If a client's OnReceive() does not respond
    // before the MessageReader interface is closed, then a future MessageReader
    // for this message queue will receive the unacknowledged message again.
    OnReceive(fuchsia.mem.Buffer message) -> ();
};