/*

  This file is provided under a dual BSD/GPLv2 license.  When using or

  redistributing this file, you may do so under either license.

  GPL LICENSE SUMMARY

  Copyright(c) 2017 Intel Corporation.

  This program is free software; you can redistribute it and/or modify

  it under the terms of version 2 of the GNU General Public License as

  published by the Free Software Foundation.

  This program is distributed in the hope that it will be useful, but

  WITHOUT ANY WARRANTY; without even the implied warranty of

  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

  General Public License for more details.

  Contact Information:

  Intel Corporation, www.intel.com

  BSD LICENSE

  Copyright(c) 2017 Intel Corporation.

  Redistribution and use in source and binary forms, with or without

  modification, are permitted provided that the following conditions

  are met:

    * Redistributions of source code must retain the above copyright

      notice, this list of conditions and the following disclaimer.

    * Redistributions in binary form must reproduce the above copyright

      notice, this list of conditions and the following disclaimer in

      the documentation and/or other materials provided with the

      distribution.

    * Neither the name of Intel Corporation nor the names of its

      contributors may be used to endorse or promote products derived

      from this software without specific prior written permission.

  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

*/

#ifndef PSM2_MQ_H

#define PSM2_MQ_H

#include <psm2.h>

#ifdef __cplusplus

extern "C" {

#endif

/*!

 * @file psm2_mq.h

 * @brief PSM2 Matched Queues

 *

 * @page psm2_mq Matched Queues interface

 *

 * The Matched Queues (MQ) interface implements a queue-based communication

 * model with the distinction that queue message consumers use a 3-tuple of

 * metadata to match incoming messages against a list of preposted receive

 * buffers.  These semantics are consistent with those presented by MPI-1.2

 * and all the features and side-effects of Message-Passing find their way into

 * Matched Queues. There is currently a single MQ context,

 * If need be, MQs may expose a function to allocate more than

 * one MQ context in the future.  Since an MQ is implicitly bound to a locally

 * opened endpoint, handle all MQ functions use an MQ handle instead of an EP

 * handle as a communication context.

 *

 * @section tagmatch MQ Tag Matching

 *

 * A successful MQ tag match requires an endpoint address (@ref psm2_epaddr_t)

 * and a 3-tuple of tag objects.  Two of the tag objects are provided by the

 * receiver when posting a receive buffer (@ref psm2_mq_irecv) and the last is

 * provided by the sender as part of every message sent (@ref psm2_mq_send and

 * @ref psm2_mq_isend).  Since MQ is a receiver-directed communication model,

 * the tag matching done at the receiver involves matching the sent message's

 * origin and send tag (@c stag) with the source endpointer address, tag (@c

 * rtag), and tag selector (@c rtagsel) attached to every preposted receive

 * buffer.  The incoming @c stag is compared to the posted @c rtag but only for

 * significant bits set to @c 1 in the @c rtagsel.  The @c rtagsel can be used

 * to mask off parts (or even all) of the bitwise comparison between sender and

 * receiver tags.  A successful match causes the message to be received into

 * the buffer with which the tag is matched.  If the incoming message is too

 * large, it is truncated to the size of the posted receive buffer.  The

 * bitwise operation corresponding to a successful match and receipt of an

 * expected message amounts to the following expression evaluating as true:

 *

 *      @verbatim ((stag ^ rtag) & rtagsel) == 0 @endverbatim

 *

 * It is up to the user to encode (pack) into the 64-bit unsigned

 * integers, including employing the @c rtagsel tag selector as a method to

 * wildcart part or all of the bits significant in the tag matching operation.

 * For example, MPI uses triple based on context (MPI communicator), source

 * rank, send tag. The following code example shows how the triple can be

 * packed into 64 bits:

 *

 * @code{.c}

 	//

 	// 64-bit send tag formed by packing the triple:

 	//

 	// ( context_id_16bits | source_rank_16bits | send_tag_32bits )

 	//

 	stag = ( (((context_id)&0xffffULL)<<48)|    \

 	         (((source_rank)&0xffffULL)<<32)|   \

 	         (((send_tag)&0xffffffffULL)) );

   @endcode

 *

 * Similarly, the receiver applies the @c rtag matching bits and @c rtagsel

 * masking bits against a list of send tags and returns the first successful

 * match.  Zero bits in the @c tagsel can be used to indicate wildcarded bits

 * in the 64-bit tag which can be useful for implementing MPI's

 * @c MPI_ANY_SOURCE and @c MPI_ANY_TAG.  Following the example bit splicing in

 * the above @c stag example:

 *

 * @code{.c}

   	// Example MPI implementation where MPI_COMM_WORLD implemented as 0x3333

   	// MPI_Irecv source_rank=MPI_ANY_SOURCE, tag=7, comm=MPI_COMM_WORLD

   	rtag    = 0x3333000000000007;

   	rtagsel = 0xffff0000ffffffff;

   	// MPI_Irecv source_rank=3, tag=MPI_ANY_TAG, comm=MPI_COMM_WORLD

   	rtag    = 0x3333000300000000;

   	rtagsel = 0xffffffff80000000; // can't ignore sign bit in tag

   	// MPI_Irecv source_rank=MPI_ANY_SOURCE, tag=MPI_ANY_TAG, comm=MPI_COMM_WORLD

   	rtag    = 0x3333000300000000;

   	rtagsel = 0xffff000080000000; // can't ignore sign bit in tag

   @endcode

 *

 *

 * Applications that do not follow tag matching semantics can simply always

 * pass a value of @c 0 for @c rtagsel, which will always yield a successful

 * match to the first preposted buffer.  If a message cannot be matched to any

 * of the preposted buffers, the message is delivered as an unexpected

 * message.

 *

 * @section mq_receive MQ Message Reception

 *

 * MQ messages are either received as @e expected or @e unexpected: @li The

 * received message is @e expected if the incoming message tag matches the

 * combination of tag and tag selector of at least one of the user-provided

 * receive buffers preposted with @ref psm2_mq_irecv.

 *

 * @li The received message is @e unexpected if the incoming message tag @b

 * doesn't match any combination of tag and tag selector from all the

 * user-provided receive buffers preposted with @ref psm2_mq_irecv.

 *

 * Unexpected messages are messages that the MQ library buffers until the

 * user provides a receive buffer that can match the unexpected message.

 * With Matched Queues and MPI alike, unexpected messages can occur as a

 * side-effect of the programming model, whereby the arrival of messages can be

 * slightly out of step with the ordering in which the user

 * provides receive buffers.  Unexpected messages can also be triggered by the

 * difference between the rate at which a sender produces messages and the rate

 * at which a paired receiver can post buffers and hence consume the messages.

 *

 * In all cases, too many @e unexpected messages will negatively affect

 * performance.  Users can employ some of the following mechanisms to reduce

 * the effect of added memory allocations and copies that result from

 * unexpected messages:

 *   @li If and when possible, receive buffers should be posted as early as

 *       possible and ideally before calling into the progress engine.

 *   @li Use of rendezvous messaging that can be controlled with

 *       @ref PSM2_MQ_RNDV_HFI_SZ and @ref PSM2_MQ_RNDV_SHM_SZ options.  These

 *       options default to values determined to make effective use of

 *       bandwidth and are hence not advisable for all communication message

 *       sizes, but rendezvous messages inherently prevent unexpected

 *       messages by synchronizing the sender with the receiver beforehand.

 *   @li The amount of memory that is allocated to handle unexpected messages

 *       can be bounded by adjusting the Global @ref PSM2_MQ_MAX_SYSBUF_MBYTES

 *       option.

 *   @li MQ statistics, such as the amount of received unexpected messages and

 *       the aggregate amount of unexpected bytes are available in the @ref

 *       psm2_mq_stats structure.

 *

 * Whenever a match occurs, whether the message is expected or unexpected, it

 * is generally up to the user to ensure that the message is not truncated.

 * Message truncation occurs when the size of the preposted buffer is less than

 * the size of the incoming matched message.  MQ will correctly handle

 * message truncation by always copying the appropriate amount of bytes as to

 * not overwrite any data.  While it is valid to send less data than the amount

 * of data that has been preposted, messages that are truncated will be marked

 * @ref PSM2_MQ_TRUNCATION as part of the error code in the message status

 * structure (@ref psm2_mq_status_t or @ref psm2_mq_status2_t).

 *

 * @section mq_completion MQ Completion Semantics

 *

 * Message completion in Matched Queues follows local completion semantics.

 * When sending an MQ message, it is deemed complete when MQ guarantees that

 * the source data has been sent and that the entire input source data memory

 * location can be safely overwritten.  As with standard Message-Passing,

 * MQ does not make any remote completion guarantees for sends.  MQ does

 * however, allow a sender to synchronize with a receiver to send a synchronous

 * message which sends a message only after a matching receive buffer has been

 * posted by the receiver (@ref PSM2_MQ_FLAG_SENDSYNC).

 *

 * A receive is deemed complete after it has matched its associated receive

 * buffer with an incoming send and that the data from the send has been

 * completely delivered to the receive buffer.

 *

 * @section mq_progress MQ Progress Requirements

 *

 * Progress on MQs must be @e explicitly ensured by the user for correctness.

 * The progress requirement holds even if certain areas of the MQ

 * implementation require less network attention than others, or if progress

 * may internally be guaranteed through interrupts.  The main polling function,

 * @ref psm2_poll, is the most general form of ensuring process on a given

 * endpoint.  Calling @ref psm2_poll ensures that progress is made over all the

 * MQs and other components instantiated over the endpoint passed to @ref

 * psm2_poll.

 *

 * While @ref psm2_poll is the only way to directly ensure progress, other MQ

 * functions will conditionally ensure progres depending on how they are used:

 *

 * @li @ref psm2_mq_wait employs polling and waits until the request is

 * completed.  For blocking communication operations where the caller is

 * waiting on a single send or receive to complete, psm2_mq_wait usually

 * provides the best responsiveness in terms of latency.

 *

 * @li @ref psm2_mq_test can test a particular request for completion, but @b

 * never directly or indirectly ensures progress as it only tests the

 * completion status of a request, nothing more.  See functional documentation

 * in @ref psm2_mq_test for a detailed discussion.

 *

 * @li @ref psm2_mq_ipeek ensures progress if and only if the MQ's completion

 * queue is empty and will not ensure progress as long as the completion queue

 * is non-empty.  Users that always aggressively process all elements of the MQ

 * completion queue as part of their own progress engine will indirectly always

 * ensure MQ progress. The ipeek mechanism is the preferred way for

 * ensuring progress when many non-blocking requests are in flight since ipeek

 * returns requests in the order in which they complete.  Depending on how the

 * user initiates and completes communication, this may be preferable to

 * calling other progress functions on individual requests.

 */

/*! @defgroup mq PSM Matched Queues

 *

 * @{

 */

/** @brief Initialize the MQ component for MQ communication

 *

 * This function provides the Matched Queue handle necessary to perform all

 * Matched Queue communication operations.

 *

 * @param[in] ep Endpoint over which to initialize Matched Queue

 * @param[in] ignored

 * @param[in] opts Set of options for Matched Queue

 * @param[in] numopts Number of options passed

 * @param[out] mq User-supplied storage to return the Matched Queue handle

 *                associated to the newly created Matched Queue.

 *

 * @remark This function can be called many times to retrieve the MQ handle

 *         associated to an endpoint, but options are only considered the first

 *         time the function is called.

 *

 * @post The user obtains a handle to an instantiated Match Queue.

 *

 * The following error code is returned.  Other errors are handled by the PSM

 * error handler (@ref psm2_error_register_handler).

 *

 * @retval PSM2_OK A new Matched Queue has been instantiated across all the

 *         members of the group.

 *

 * @code{.c}

   	int try_open_endpoint_and_initialize_mq(

   	       psm2_ep_t *ep,	// endpoint handle

   	       psm2_epid_t *epid, // unique endpoint ID

   	       psm2_uuid_t job_uuid, // unique job uuid, for ep_open

   	       psm2_mq_t *mq, // MQ handle initialized on endpoint 'ep'

   	       uint64_t communicator_bits) // Where we store our communicator or

   	                                   // context bits in the 64-bit tag.

   	{

   	    // Simplified open, see psm2_ep_open documentation for more info

   	    psm2_ep_open(job_uuid,

   	                NULL, // no options

   	                ep, epid);

   	    // We initialize a matched queue by telling PSM the bits that are

   	    // order-significant in the tag.  Point-to-point ordering will not be

   	    // maintained between senders where the communicator bits are not the

   	    // same.

   	    psm2_mq_init(ep,

   	                communicator_bits,

   	                NULL, // no other MQ options

   	                0,    // 0 options passed

   	                mq);  // newly initialized matched Queue

   	    return 1;

   	}

   @endcode

 */

psm2_error_t

psm2_mq_init(psm2_ep_t ep, uint64_t ignored,

	    const struct psm2_optkey *opts, int numopts, psm2_mq_t *mq);

#define PSM2_MQ_ORDERMASK_NONE	0ULL

	/**< This macro is reserved for future tag order masking support. */

#define PSM2_MQ_ORDERMASK_ALL	0xffffffffffffffffULL

	/**< This macro is reserved for future tag order masking support. */

/** @brief Finalize (close) an MQ handle

 *

 * The following error code is returned.  Other errors are handled by the PSM

 * error handler (@ref psm2_error_register_handler).

 *

 * @retval PSM2_OK A given Matched Queue has been freed and use of the future

 * use of the handle produces undefined results.

 */

psm2_error_t

psm2_mq_finalize(psm2_mq_t mq);

#define PSM2_MQ_TAG_ELEMENTS 4

	/**< Represents the number of 32-bit tag elements in the psm2_mq_tag_t

	 *   type plus one extra element to keep alignment and padding

	 *   as 16 bytes.  */

/** @struct psm2_mq_tag

 ** @brief MQ Message tag

 *

 * Extended message tag type introduced in PSM 2.0.  The previous 64 bit tag

 * values are replaced by a struct containing three 32 bit tag values for a

 * total of 96 bits.  Matching semantics are unchanged from the previous 64-bit

 * matching scheme; the only difference is that 96 bits are matched instead of

 * 64.  For interoperability with existing PSM routines, 64 bit tags are

 * extended to a 96 bit tag by setting the upper 32 bits (tag[2] or tag2) to

 * zero.  Other than this caveat, all of the existing routines using 64-bit

 * tags are interchangeable with PSM2 routines using this psm2_mq_tag_t type.

 * For example, a message sent using @ref psm2_mq_send can be received using

 * @ref psm2_mq_irecv2, provided the tags match as described above.

 */

typedef

//struct psm2_mq_tag {

union psm2_mq_tag {

//    union {

		uint32_t tag[PSM2_MQ_TAG_ELEMENTS]; /* No longer specifying

						     * alignment as it makes

						     * code break with newer

						     * compilers. */

            /**< 3 x 32bit array representation of @ref psm2_mq_tag */

		struct {

			uint32_t tag0; /**< 1 of 3 uint32_t tag values */

			uint32_t tag1; /**< 2 of 3 uint32_t tag values */

			uint32_t tag2; /**< 3 of 3 uint32_t tag values */

		};

//	};

} psm2_mq_tag_t;

/** @brief MQ Non-blocking operation status

 *

 * Message completion status for asynchronous communication operations.

 * For wait and test functions, MQ fills in the structure upon completion.

 * Upon completion, receive requests fill in every field of the status

 * structure while send requests only return a valid error_code and context

 * pointer.

 */

typedef

struct psm2_mq_status {

	/** Sender's original message tag (receive reqs only) */

	uint64_t msg_tag;

	/** Sender's original message length (receive reqs only) */

	uint32_t msg_length;

	/** Actual number of bytes transfered (receive reqs only) */

	uint32_t nbytes;

	/** MQ error code for communication operation */

	psm2_error_t error_code;

	/**< User-associated context for send or receive */

	void *context;

} psm2_mq_status_t;

/** @brief MQ Non-blocking operation status

 *

 * Message completion status for asynchronous communication operations.  For

 * wait and test functions, MQ fills in the structure upon completion.  Upon

 * completion, requests fill in every field of the status structure with the

 * exception of the nbytes field, which is only valid for receives.  Version 2

 * of the status type contains an @ref psm2_mq_tag_t type to represent the tag

 * instead of a 64-bit integer value and is for use with PSM v2 routines.

 */

typedef

struct psm2_mq_status2 {

	/** Remote peer's epaddr */

	psm2_epaddr_t msg_peer;

	/** Sender's original message tag */

	psm2_mq_tag_t msg_tag __attribute__ ((aligned(16)));/* Alignment added

							     * to preserve the

							     * layout as is

							     * expected by

							     * existent code */

	/** Sender's original message length */

	uint32_t msg_length;

	/** Actual number of bytes transfered (receiver only) */

	uint32_t nbytes;

	/** MQ error code for communication operation */

	psm2_error_t error_code;

	/** User-associated context for send or receive */

	void *context;

} psm2_mq_status2_t;

/** @brief PSM2 Communication handle (opaque) */

typedef struct psm2_mq_req *psm2_mq_req_t;

/** @brief MQ Request Struct

 *

 * Message completion request for asynchronous communication operations.

 * Upon completion, requests are filled with the valid data for the

 * corresponding send/recv operation that was completed. This datatype

 * contains the status data and is converted into the

 * mq_status structures in wait/test functions.

 */

struct psm2_mq_req_user {

	/* Tag matching vars */

	psm2_epaddr_t peer;

	psm2_mq_tag_t tag __attribute__ ((aligned(16)));/* Alignment added

							 * to preserve the

							 * layout as is

							 * expected by

							 * existent code */

	psm2_mq_tag_t tagsel;	/* used for receives */

	/* Buffer attached to request.  May be a system buffer for unexpected

	 * messages or a user buffer when an expected message */

	uint8_t *buf;

	uint32_t buf_len;

	uint32_t error_code;

	uint32_t recv_msglen;	/* Message length we are ready to receive */

	uint32_t send_msglen;	/* Message length from sender */

	/* Used for request to send messages */

	void *context;		/* user context associated to sends or receives */

	uint64_t user_reserved[4];

};

/*! @} */

/*! @ingroup mq

 * @defgroup mq_options PSM Matched Queue Options

 * @{

 *

 * MQ options can be modified at any point at runtime, unless otherwise noted.

 * The following example shows how to retrieve the current message size at

 * which messages are sent as synchronous.

 *

 * @code{.c}

   	uint32_t get_hfirv_size(psm2_mq_t mq)

   	{

   	    uint32_t rvsize;

   	    psm2_getopt(mq, PSM2_MQ_RNDV_HFI_SZ, &rvsize);

   	    return rvsize;

   	}

   @endcode

 */

/** @brief Get an MQ option (Deprecated. Use psm2_getopt with PSM2_COMPONENT_MQ)

 *

 * Function to retrieve the value of an MQ option.

 *

 * @param[in] mq Matched Queue handle

 * @param[in] option Index of option to retrieve.  Possible values are:

 *            @li @ref PSM2_MQ_RNDV_HFI_SZ

 *            @li @ref PSM2_MQ_RNDV_SHM_SZ

 *            @li @ref PSM2_MQ_MAX_SYSBUF_MBYTES

 *

 * @param[in] value Pointer to storage that can be used to store the value of

 *            the option to be set.  It is up to the user to ensure that the

 *            pointer points to a memory location large enough to accommodate

 *            the value associated to the type.  Each option documents the size

 *            associated to its value.

 *

 * @returns PSM2_OK if option could be retrieved.

 * @returns PSM2_PARAM_ERR if the option is not a valid option number

 */

psm2_error_t psm2_mq_getopt(psm2_mq_t mq, int option, void *value);

/** @brief Set an MQ option (Deprecated. Use psm2_setopt with PSM2_COMPONENT_MQ)

 *

 * Function to set the value of an MQ option.

 *

 * @param[in] mq Matched Queue handle

 * @param[in] option Index of option to retrieve.  Possible values are:

 *            @li @ref PSM2_MQ_RNDV_HFI_SZ

 *            @li @ref PSM2_MQ_RNDV_SHM_SZ

 *            @li @ref PSM2_MQ_MAX_SYSBUF_MBYTES

 *

 * @param[in] value Pointer to storage that contains the value to be updated

 *                  for the supplied option number.  It is up to the user to

 *                  ensure that the pointer points to a memory location with a

 *                  correct size.

 *

 * @returns PSM2_OK if option could be retrieved.

 * @returns PSM2_PARAM_ERR if the option is not a valid option number

 * @returns PSM2_OPT_READONLY if the option to be set is a read-only option

 *                           (currently no MQ options are read-only).

 */

psm2_error_t psm2_mq_setopt(psm2_mq_t mq, int option, const void *value);

/*! @}  */

/*! @ingroup mq

 * @{

 */

#define PSM2_MQ_FLAG_SENDSYNC	0x01

				/**< MQ Send Force synchronous send */

#define PSM2_MQ_REQINVALID	((psm2_mq_req_t)(NULL))

				/**< MQ request completion value */

#define PSM2_MQ_ANY_ADDR		((psm2_epaddr_t)NULL)

				/**< MQ receive from any source epaddr */

/** @brief MQ fast-path operation enumeration

 *

 * To provide for quick enqueing of send/receives from within an AM handler

 * PSM2 provdes fast path send/recv options that will enqueue those ops

 * into the MQ. The supported operations to call in fast path are enumerated

 * in the @ref psm2_mq_fp_op enum.

 */

enum psm2_mq_fp_op {

	PSM2_MQ_ISEND_FP = 1,

	PSM2_MQ_IRECV_FP,

};

/** @brief Post a fast-path isend/irecv into the MQ

 *

 * Function to only enqueue fast-path non-blocking sends or non-blocking recvs

 * into a particular MQ. These calls only work if the process already holds

 * the mq progress lock, this case traditionally only applies to calls from

 * a registered AM Handler.

 *

 * This function helps to enable one-sided communication models from middleware

 * such as OFI to provide fast >2KB message transfers for RMA operations.

 *

 * When posting irecvs every MQ message received on a particular MQ,

 * the @c tag and @c tagsel parameters are used against the incoming

 * message's send tag as described in @ref tagmatch.

 *

 * When posting isends the user gurantees that the source data will remain

 * unmodified until the send is locally completed through a call such as

 * @ref psm2_mq_wait or @ref psm2_mq_test.

 *

 * Progress on the operations enqueued into the MQ will may not occur until

 * the next PSM2 progress API is invoked.

 *

 * @param[in] ep PSM2 endpoint

 * @param[in] mq Matched Queue Handle

 * @param[in] addr Destination EP address (used only on isends)

 * @param[in] tag Send/Receive tag

 * @param[in] tagsel Receive tag selector (used only on irecvs)

 * @param[in] flags Send/Receive Flags

 * @param[in] buf Send/Receive buffer

 * @param[in] len Send/Receive buffer length

 * @param[in] context User context pointer, available in @ref psm2_mq_status_t

 *                    upon completion

 * @param[in] fp_type Fast-path op requested

 * @param[out] req PSM MQ Request handle created by the preposted receive, to

 *                 be used for explicitly controlling message receive

 *                 completion.

 *

 * @post The supplied buffer is given to MQ to match against incoming

 *       messages unless it is cancelled via @ref psm2_mq_cancel @e before any

 *       match occurs.

 *

 * @remark This function may be called simultaneously from multiple threads

 * 	   as long as different MQ arguments are used in each of the calls.

 *

 * The following error code is returned.  Other errors are handled by the PSM

 * error handler (@ref psm2_error_register_handler).

 *

 * @retval PSM2_OK The receive buffer has successfully been posted to the MQ.

 */

psm2_error_t

psm2_mq_fp_msg(psm2_ep_t ep, psm2_mq_t mq, psm2_epaddr_t addr, psm2_mq_tag_t *tag,

		psm2_mq_tag_t *tagsel, uint32_t flags, void *buf, uint32_t len,

		void *context, enum psm2_mq_fp_op fp_type, psm2_mq_req_t *req);

/** @brief Post a receive to a Matched Queue with tag selection criteria

 *

 * Function to receive a non-blocking MQ message by providing a preposted

 * buffer. For every MQ message received on a particular MQ, the @c tag and @c

 * tagsel parameters are used against the incoming message's send tag as

 * described in @ref tagmatch.

 *

 * @param[in] mq Matched Queue Handle

 * @param[in] rtag Receive tag

 * @param[in] rtagsel Receive tag selector

 * @param[in] flags Receive flags (None currently supported)

 * @param[in] buf Receive buffer

 * @param[in] len Receive buffer length

 * @param[in] context User context pointer, available in @ref psm2_mq_status_t

 *                    upon completion

 * @param[out] req PSM MQ Request handle created by the preposted receive, to

 *                 be used for explicitly controlling message receive

 *                 completion.

 *

 * @post The supplied receive buffer is given to MQ to match against incoming

 *       messages unless it is cancelled via @ref psm2_mq_cancel @e before any

 *       match occurs.

 *

 * @remark This function may be called simultaneously from multiple threads

 * 	   as long as different MQ arguments are used in each of the calls.

 *

 * The following error code is returned.  Other errors are handled by the PSM

 * error handler (@ref psm2_error_register_handler).

 *

 * @retval PSM2_OK The receive buffer has successfully been posted to the MQ.

 */

psm2_error_t

psm2_mq_irecv(psm2_mq_t mq, uint64_t rtag, uint64_t rtagsel, uint32_t flags,

	     void *buf, uint32_t len, void *context, psm2_mq_req_t *req);

/** @brief Post a receive to a Matched Queue with source and tag selection

 *  criteria

 *

 * Function to receive a non-blocking MQ message by providing a preposted

 * buffer. For every MQ message received on a particular MQ, the @c src, @c tag

 * and @c tagsel parameters are used against the incoming message's send tag as

 * described in @ref tagmatch.

 *

 * @param[in] mq Matched Queue Handle

 * @param[in] src Source (sender's) epaddr (may be PSM2_MQ_ANY_ADDR)

 * @param[in] rtag Receive tag

 * @param[in] rtagsel Receive tag selector

 * @param[in] flags Receive flags (None currently supported)

 * @param[in] buf Receive buffer

 * @param[in] len Receive buffer length

 * @param[in] context User context pointer, available in @ref psm2_mq_status2_t

 *                    upon completion

 * @param[out] req PSM MQ Request handle created by the preposted receive, to

 *                 be used for explicitly controlling message receive

 *                 completion.

 *

 * @post The supplied receive buffer is given to MQ to match against incoming

 *       messages unless it is cancelled via @ref psm2_mq_cancel @e before any

 *       match occurs.

 *

 * @remark This function may be called simultaneously from multiple threads

 * 	   as long as different MQ arguments are used in each of the calls.

 *

 * The following error code is returned.  Other errors are handled by the PSM

 * error handler (@ref psm2_error_register_handler).

 *

 * @retval PSM2_OK The receive buffer has successfully been posted to the MQ.

 */

psm2_error_t

psm2_mq_irecv2(psm2_mq_t mq, psm2_epaddr_t src, psm2_mq_tag_t *rtag,

	      psm2_mq_tag_t *rtagsel, uint32_t flags, void *buf, uint32_t len,

	      void *context, psm2_mq_req_t *req);

/** @brief Post a receive to a Matched Queue with matched request

 *

 * Function to receive a non-blocking MQ message by providing a preposted

 * buffer. The provided request should already be matched using the @ref

 * psm2_mq_improbe or @ref psm2_mq_improbe2 routines.  It is an error to pass a

 * request that has not already been matched by one of those routines.

 *

 * @param[in] mq Matched Queue Handle

 * @param[in] flags Receive flags (None currently supported)

 * @param[in] buf Receive buffer

 * @param[in] len Receive buffer length

 * @param[in] context User context pointer, available in @ref psm2_mq_status_t

 *                    upon completion

 * @param[inout] reqo PSM MQ Request handle matched previously by a matched

 *		     probe routine (@ref psm2_mq_improbe or @ref

 *		     psm2_mq_improbe2), also to be used for explicitly

 *		     controlling message receive completion.

 *

 * @post The supplied receive buffer is given to MQ to deliver the matched

 *       message.

 *

 * @remark This function may be called simultaneously from multiple threads

 * 	   as long as different MQ arguments are used in each of the calls.

 *

 * The following error code is returned.  Other errors are handled by the PSM

 * error handler (@ref psm2_error_register_handler).

 *

 * @retval PSM2_OK The receive buffer has successfully been posted to the MQ.

 */

psm2_error_t

psm2_mq_imrecv(psm2_mq_t mq, uint32_t flags, void *buf, uint32_t len,

	      void *context, psm2_mq_req_t *reqo);

/** @brief Send a blocking MQ message

 *

 * Function to send a blocking MQ message, whereby the message is locally

 * complete and the source data can be modified upon return.

 *

 * @param[in] mq Matched Queue Handle

 * @param[in] dest Destination EP address

 * @param[in] flags Message flags, currently:

 *            @li PSM2_MQ_FLAG_SENDSYNC tells PSM to send the message

 *            synchronously, meaning that the message will not be sent until

 *            the receiver acknowledges that it has matched the send with a

 *            receive buffer.

 * @param[in] stag Message Send Tag

 * @param[in] buf Source buffer pointer

 * @param[in] len Length of message starting at @c buf.

 *

 * @post The source buffer is reusable and the send is locally complete.

 *

 * @remark This function may be called simultaneously from multiple threads

 * 	   as long as different MQ arguments are used in each of the calls.

 *

 * @note This send function has been implemented to best suit MPI_Send.

 *

 * The following error code is returned.  Other errors are handled by the PSM

 * error handler (@ref psm2_error_register_handler).

 *

 * @retval PSM2_OK The message has been successfully sent.

 */

psm2_error_t

psm2_mq_send(psm2_mq_t mq, psm2_epaddr_t dest, uint32_t flags, uint64_t stag,

	    const void *buf, uint32_t len);

/** @brief Send a blocking MQ message

 *

 * Function to send a blocking MQ message, whereby the message is locally

 * complete and the source data can be modified upon return.

 *

 * @param[in] mq Matched Queue Handle

 * @param[in] dest Destination EP address

 * @param[in] flags Message flags, currently:

 *            @li PSM2_MQ_FLAG_SENDSYNC tells PSM to send the message

 *            synchronously, meaning that the message will not be sent until

 *            the receiver acknowledges that it has matched the send with a

 *            receive buffer.

 * @param[in] stag Message Send Tag

 * @param[in] buf Source buffer pointer

 * @param[in] len Length of message starting at @c buf.

 *

 * @post The source buffer is reusable and the send is locally complete.

 *

 * @remark This function may be called simultaneously from multiple threads

 * 	   as long as different MQ arguments are used in each of the calls.

 *

 * @note This send function has been implemented to best suit MPI_Send.

 *

 * The following error code is returned.  Other errors are handled by the PSM

 * error handler (@ref psm2_error_register_handler).

 *

 * @retval PSM2_OK The message has been successfully sent.

 */

psm2_error_t

psm2_mq_send2(psm2_mq_t mq, psm2_epaddr_t dest, uint32_t flags,

	     psm2_mq_tag_t *stag, const void *buf, uint32_t len);

/** @brief Send a non-blocking MQ message

 *

 * Function to initiate the send of a non-blocking MQ message, whereby the

 * user guarantees that the source data will remain unmodified until the send

 * is locally completed through a call such as @ref psm2_mq_wait or @ref

 * psm2_mq_test.

 *

 * @param[in] mq Matched Queue Handle

 * @param[in] dest Destination EP address

 * @param[in] flags Message flags, currently:

 *            @li PSM2_MQ_FLAG_SENDSYNC tells PSM to send the message

 *            synchronously, meaning that the message will not be sent until

 *            the receiver acknowledges that it has matched the send with a

 *            receive buffer.

 * @param[in] stag Message Send Tag

 * @param[in] buf Source buffer pointer

 * @param[in] len Length of message starting at @c buf.

 * @param[in] context Optional user-provided pointer available in @ref

 *                    psm2_mq_status_t when the send is locally completed.

 * @param[out] req PSM MQ Request handle created by the non-blocking send, to

 *                 be used for explicitly controlling message completion.

 *

 * @post The source buffer is not reusable and the send is not locally complete

 *       until its request is completed by either @ref psm2_mq_test or @ref

 *       psm2_mq_wait.

 *

 * @remark This function may be called simultaneously from multiple threads

 * 	   as long as different MQ arguments are used in each of the calls.

 *

 * @note This send function has been implemented to suit MPI_Isend.

 *

 * The following error code is returned.  Other errors are handled by the PSM

 * error handler (@ref psm2_error_register_handler).

 *

 * @retval PSM2_OK The message has been successfully initiated.

 *

 * @code{.c}

   	psm2_mq_req_t

   	non_blocking_send(const psm2_mq_t mq, psm2_epaddr_t dest_ep,

   	                      const void *buf, uint32_t len,

   	     		 int context_id, int send_tag, const my_request_t *req)

   	{

   	    psm2_mq_req_t req_mq;

   	    // Set up our send tag, assume that "my_rank" is global and represents

   	    // the rank of this process in the job

   	    uint64_t tag = ( ((context_id & 0xffff) << 48) |

   	                     ((my_rank & 0xffff) << 32)    |

   	                     ((send_tag & 0xffffffff)) );

   	    psm2_mq_isend(mq, dest_ep,

   	                 0, // no flags

   	                 tag,

   	                 buf,

   	                 len,

   	                 req, // this req is available in psm2_mq_status_t when one

   	                      // of the synchronization functions is called.

   	                 &req_mq);

   	    return req_mq;

   	}

   @endcode

 */

psm2_error_t

psm2_mq_isend(psm2_mq_t mq, psm2_epaddr_t dest, uint32_t flags, uint64_t stag,

	     const void *buf, uint32_t len, void *context, psm2_mq_req_t *req);

/** @brief Send a non-blocking MQ message

 *

 * Function to initiate the send of a non-blocking MQ message, whereby the

 * user guarantees that the source data will remain unmodified until the send

 * is locally completed through a call such as @ref psm2_mq_wait or @ref

 * psm2_mq_test.

 *

 * @param[in] mq Matched Queue Handle

 * @param[in] dest Destination EP address

 * @param[in] flags Message flags, currently:

 *            @li PSM2_MQ_FLAG_SENDSYNC tells PSM to send the message

 *            synchronously, meaning that the message will not be sent until

 *            the receiver acknowledges that it has matched the send with a

 *            receive buffer.

 * @param[in] stag Message Send Tag, array of three 32-bit values.

 * @param[in] buf Source buffer pointer

 * @param[in] len Length of message starting at @c buf.

 * @param[in] context Optional user-provided pointer available in @ref

 *                    psm2_mq_status2_t when the send is locally completed.

 * @param[out] req PSM MQ Request handle created by the non-blocking send, to

 *                 be used for explicitly controlling message completion.

 *

 * @post The source buffer is not reusable and the send is not locally complete

 *       until its request is completed by either @ref psm2_mq_test or @ref

 *       psm2_mq_wait.

 *

 * @remark This function may be called simultaneously from multiple threads

 * 	   as long as different MQ arguments are used in each of the calls.

 *

 * @note This send function has been implemented to suit MPI_Isend.

 *

 * The following error code is returned.  Other errors are handled by the PSM

 * error handler (@ref psm2_error_register_handler).

 *

 * @retval PSM2_OK The message has been successfully initiated.

 *

 * @code{.c}

   	psm2_mq_req_t

   	non_blocking_send(const psm2_mq_t mq, psm2_epaddr_t dest_ep,

   	                      const void *buf, uint32_t len,

   	     		 int context_id, int send_tag, const my_request_t *req)

   	{

   	    psm2_mq_req_t req_mq;

   	    // Set up our send tag, assume that "my_rank" is global and represents

   	    // the rank of this process in the job

   	    psm2_mq_tag_t tag;

   	    tag.tag[0] = send_tag;

   	    tag.tag[1] = my_rank;

   	    tag.tag[2] = context_id;

   	    psm2_mq_isend(mq, dest_ep,

   	                 0, // no flags