# Mailboxes are objects that enable synchronous IPC via arbitrary
# message-passing of tagged data and/or handles. Not as efficient
# as shared memory channels, but more flexible.

object mailbox : object {
    uid 99934ad04ece1e07

    capabilities [
        send
        receive
        close
    ]

    method create [constructor]
    method close [destructor cap:close]

    # Send a message to the reciever, and block until a response is
    # sent. Note that getting this response does not require the
    # receive capability.
    method call [cap:send] {
        param tag uint64 [inout]
        param data buffer [optional inout]
        param data_size size  # number of total bytes in data buffer
        param handles ref object [optional inout handle list]
        param handles_size size  # total size of handles buffer
    }

    # Respond to a message sent using call, and wait for another
    # message to arrive. Note that this does not require the send
    # capability. A reply tag of 0 skips the reply and goes directly
    # to waiting for a new message.
    method respond [cap:receive] {
        param tag uint64 [inout]
        param data buffer [optional inout]
        param data_size size  # number of total bytes in data buffer
        param handles ref object [optional inout handle list]
        param handles_size size  # total size of handles buffer
        param reply_tag uint64 [inout]
        param flags uint64
    }
}
