index 8efaa2c310c3711d01cd3788e5998222e76d7651..194767210ff1dd110b9b131e37b7f1c9d51b666f 100644 (file)
*/
#define MessageQ_E_UNBLOCKED (-19)
+/*!
+ * @brief MessageQ was shutdown
+ */
+#define MessageQ_E_SHUTDOWN (-20)
+
/* =============================================================================
* Macros
* =============================================================================
* @brief Required first field in every message
*/
typedef struct {
- Bits32 reserved0; /*!< reserved for List.elem->next */
- Bits32 reserved1; /*!< reserved for List.elem->prev */
+ Bits64 reserved0; /*!< reserved for List.elem->next */
+ Bits64 reserved1; /*!< reserved for List.elem->prev */
Bits32 msgSize; /*!< message size */
Bits16 flags; /*!< bitmask of different flags */
Bits16 msgId; /*!< message id */
* =============================================================================
*/
+/** @cond INTERNAL */
+/* Returns the local handle associated with queueId. */
+MessageQ_Handle MessageQ_getLocalHandle(MessageQ_QueueId queueId);
+/** @endcond INTERNAL */
+
+
/** @cond INTERNAL */
Void MessageQ_Params_init__S(MessageQ_Params *params, Int version);
/** @endcond INTERNAL */
*/
MessageQ_Handle MessageQ_create(String name, const MessageQ_Params *params);
+/*!
+ * @brief Announce a previously created MessageQ to NameServer
+ * (Linux/Android only)
+ *
+ * The name supplied here does not have to be in persistent memory. The
+ * maximum length of the string supplied here, including the '\\0' terminator,
+ * is '32' by default.
+ *
+ * There are no verifications to ensure that the name supplied in
+ * MessageQ_announce() is unique across all processors. Caution must be
+ * exercised to ensure that each processor uses a unique name.
+ *
+ * @param[in] name Name of the queue
+ * @param[in] handlePtr Pointer to handle returned from MessageQ_create.
+ *
+ * @return MessageQ status:
+ * - #MessageQ_E_FAIL: announce failed
+ * - #MessageQ_S_SUCCESS: announce successful
+ */
+Int MessageQ_announce(String name, MessageQ_Handle * handlePtr);
+
/*!
* @brief Create a MessageQ instance using the type MessageQ_Params2
*
Int MessageQ_open(String name, MessageQ_QueueId *queueId);
/*!
- * @brief Opens a MessageQ given the queue index and remote processor ID
+ * @brief Open a MessageQ given the queue index and processor ID
*
* This function can be used instead of MessageQ_open() if the queue
* was created with a reserved queue index. In the example below, the
* MessageQ_Params params;
*
* MessageQ_Params_init(¶ms);
- * params.queueIndex = SERVER_QIDX;
- * messageQ = MessageQ_create("server", ¶ms);
+ * params.queueIndex = SERVER_QUEIDX;
+ * messageQ = MessageQ_create(NULL, ¶ms);
* ...
* }
*
* opened has already been created. MessageQ_openQueueId() does not validate
* that the queue has been created (unlike the MessageQ_open() function).
*
- * @param[in] queueIndex QueueIndex specified in MessageQ_Params
- * @param[in] remoteProcId Multiproc_Id of where the created queue resides
+ * @param[in] queueIndex QueueIndex specified in MessageQ_Params when
+ * the message queue was created.
+ * @param[in] procId Multiproc_Id of where the created queue resides.
*
* @return The MessageQ_QueueId associated with the queueIndex
* and remoteProcId
* returns immediately and if no message is available, the msg
* is set to NULL and the status is #MessageQ_E_TIMEOUT. The
* #MessageQ_E_UNBLOCKED status is return, if MessageQ_unblock is called
- * on the MessageQ handle. If a message is successfully retrieved, the msg
- * is set to the message and a #MessageQ_S_SUCCESS status is returned.
+ * on the MessageQ handle. The #MessageQ_E_SHUTDOWN status is returned if
+ * MessageQ_shutdown is called on the MessageQ handle. If a message is
+ * successfully retrieved, the msg is set to the message and a
+ * #MessageQ_S_SUCCESS status is returned.
*
* @param[in] handle MessageQ handle
* @param[out] msg Pointer to the message
*
* @sa MessageQ_put()
* @sa MessageQ_unblock()
+ * @sa MessageQ_shutdown()
*/
Int MessageQ_get(MessageQ_Handle handle, MessageQ_Msg *msg, UInt timeout);
* @param[in] handle MessageQ handle
*
* @sa MessageQ_get
+ * @sa MessageQ_shutdown()
*/
Void MessageQ_unblock(MessageQ_Handle handle);
+/*!
+ * @brief Shuts down a MessageQ
+ *
+ * Similar to MessageQ_unblock(), MessageQ_shutdown() unblocks a reader thread
+ * that is blocked on a MessageQ_get(), but causes a different return code
+ * to be returned from MessageQ_get(). The MessageQ_get() call will return
+ * with status #MessageQ_E_SHUTDOWN indicating that it returned due to a
+ * MessageQ_shutdown() rather than MessageQ_unblock(), a timeout or a
+ * received message. This call is intended to be used by MessageQ transports
+ * when the transport detects that the transport framework corresponding to
+ * the MessageQ has become unusable. This call should only be used during a
+ * shutdown sequence in order to ensure that there is no blocked reader on a
+ * queue before deleting the queue. A queue may not be used after it has been
+ * shut down.
+ *
+ * MessageQ_shutdown() works by raising a flag in the queue indicating that it
+ * is shut down and then signaling the synchronizer that is configured with
+ * the target queue. If MessageQ_shutdown() is called upon a queue that has
+ * no blocked listeners, then any subsequent MessageQ_get will not block and
+ * will immediately return #MessageQ_E_SHUTDOWN regardless of whether there
+ * is a message on the queue.
+ *
+ * Restrictions:
+ * - A queue may not be used after it has been shut down.
+ * - MessageQ_shutdown() may only be called on a local queue.
+ * - May only be used with a queue configured with a blocking synchronizer.
+ *
+ * @param[in] handle MessageQ handle
+ *
+ * @sa MessageQ_get
+ * @sa MessageQ_unblock
+ */
+Void MessageQ_shutdown(MessageQ_Handle handle);
+
#if defined (__cplusplus)
}
#endif /* defined (__cplusplus) */