/* -------------------------------------------------------------------------- */
/*
** MIAMI API
*/
/* -------------------------------------------------------------------------- */

#ifndef _MIAMI_H_
#define _MIAMI_H_



int miami_init(char *host1, int port1, char *host2, int port2); 
/*

    Must be called before any other functions in this API.
    Both hosts must call miami_init(). Host 1 and port 1
    refers to the local host, while host 2 and port 2 refer to
    the remote host. That means an application calling miami_init()
    will use a different order of arguments on the two hosts
    it starts up; e.g:

	On host 1: miami_init("host1", 55043, "host2", 61200);
	On host 2: miami_init("host2", 61200, "host1", 55043);

    The function may be implemented such that it
    blocks until all participating processes have called
    miami_init(). However, that is not required.

    The function returns 0 on success, and -1 otherwise.

*/



void miami_finalize(void);
/*
    Both processes must call this function before they exit. After
    miami_finalize() has been called, no other functions in this API,
    including miami_init(), must be called again.
*/



int miami_tx_start(void *buf, int bytes, int tag);
/*
    This function initiates a start of a message send. The function
    does not block and will send the number of bytes specified
    from location buffer to the second host. The tag is used for
    matching on the receive side.

    The function returns -1 in case of an error, and a handle
    otherwise.  The handle is used when calling miami_tx_done().
    miami_tx_start() is non-blocking. That means that, especially
    for large sends, the function will return before all of the
    data in buffer has been sent. The user is expected to call
    miami_progress() once in a while to returns control to the
    protocol implementation so it can make progress.

    While a send is in progress, until miami_tx_done() returns 1,
    the user must not write or modify the send buffer.
*/



int miami_tx_done(int handle);
/*
    Check for send completion. The handle is the opaque object that
    miami_tx_start() returned. miami_tx_done() returns 1 if that
    particular send has completed, and 0 otherwise.

    Send completion means that the application can reuse the buffer
    that was passed to miami_tx_start(). It does not necessarily mean
    the message has been completely delivered at the receive side.
*/



void miami_progress(void);
/*
    A user program is expected to call this function once in a while,
    if it does not call any other the other MIAMI functions for
    a long time. For example, during long computations, while no
    message passing functions need to be called by the application,
    miami_progress() needs to be called so the MIAMI implementation
    can make progress.

    While in this function the implementation is expected to check
    for incoming messages and send more data on outstanding sends
    if possible.  Most other MIAMI functions should call this
    function when they have performed their own tasks, or are
    waiting for events.
*/




int miami_rx_start(void *buf, int bytes, int tag);
/*
    This function initiates a receive. It lets the application
    provide a buffer to receive a message into, and a number of
    bytes it is willing to accept. If a message is longer than
    "bytes", it is truncated to that value. If it is shorter, it
    is placed in the buffer without altering any of the bytes in
    the buffer that follow the message content.

    The tag is used to match incoming messages. Only messages with
    a matching tag will be accepted.  Tag is 0 or any positive value.

    Each call to miami_rx_start() can receive a single message.

    miami_rx_start() is non-blocking. That means when miami_rx_start()
    returns, the message may not have arrived yet. use miami_rx_done()
    to check whether a receive is complete or not.

    miami_rx_start() may be called any time: before a matching
    message has been sent, or after. It returns -1 in case of
    an error, or a handle that can be passed to miami_rx_done()
    in case of success.
*/



int miami_rx_done(int handle, int *bytes);
/*
    This function checks whether a particular receive has
    completed. If it returns 1, then the message has been deposited
    into the buffer provided to miami_rx_start() and the number of
    bytes actually received is returned in "bytes". If the receive
    is not done yet, 0 is returned.
*/


#endif /* _MIAMI_H_ */