From 151a4f7f9354583f183b5fe1ec5f4fe83c6d2262 Mon Sep 17 00:00:00 2001 From: John Scipione Date: Fri, 31 Jan 2020 21:50:11 -0500 Subject: [PATCH] API Docs: Clarify BLooper::PostMessage and BMessenger::SendMessage ... docs to make it clear which methods work synchronously and which work asynchronously. A small number of related edits are included as well as a couple of pedantic whitespace changes. Clarify sync vs. async reply handling better in BMessenger class description. Add The to make sentences. Change-Id: I3069934fc5e82dda25331e85884d6d0c0c100dfd Reviewed-on: https://review.haiku-os.org/c/haiku/+/2178 Reviewed-by: waddlesplash --- docs/user/app/Looper.dox | 14 ++++----- docs/user/app/Messenger.dox | 59 ++++++++++++++++++++++++------------- 2 files changed, 45 insertions(+), 28 deletions(-) diff --git a/docs/user/app/Looper.dox b/docs/user/app/Looper.dox index 482c0f909c..d04063df25 100644 --- a/docs/user/app/Looper.dox +++ b/docs/user/app/Looper.dox @@ -220,7 +220,7 @@ Posting a message puts it in the message queue. The message passes through the default handler chain. - \param command The \c what identifier of the message that needs to be sent. + \param command The \c what identifier of the message to be sent. \return A status code. \retval B_OK The operation succeeded, and the message is sent to the port. @@ -262,7 +262,7 @@ \retval B_OK The operation succeeded, and the message is sent to the port. \retval B_ERROR There was a general operation error. \retval B_BAD_VALUE This looper is not yet running and therefore cannot - receive messages. + receive messages. \see PostMessage(uint32) if you want to send a message without data members. @@ -278,9 +278,9 @@ /*! \fn status_t BLooper::PostMessage(uint32 command, BHandler* handler, BHandler* replyTo) - \brief Send a message with the \a command as \c what identifier to the - \a handler associated with this looper, and (optionally) request a - reply. + \brief Sends a message with \a command \c what identifier to the + \a handler associated with this looper. A response may be sent to the + \a replyTo handler asynchronously. The target \a handler should be associated with this looper. This method bypasses the default message queue. @@ -313,8 +313,8 @@ /*! \fn status_t BLooper::PostMessage(BMessage* message, BHandler* handler, BHandler* replyTo) - \brief Send a \a message to the \a handler associated with this looper, - and (optionally) request a reply. + \brief Send a \a message to the \a handler associated with this looper. + A response may be sent to the \a replyTo handler asynchronously. The target \a handler should be associated with this looper. This method bypasses the default message queue. diff --git a/docs/user/app/Messenger.dox b/docs/user/app/Messenger.dox index 100fab7f1a..30ff0ea9d5 100644 --- a/docs/user/app/Messenger.dox +++ b/docs/user/app/Messenger.dox @@ -36,6 +36,11 @@ is roughly equivalent in terms of efficiency to posting a message directly to the messenger's target (i.e. BLooper::PostMessage()). + If you supply a target BMessenger or BHandler to SendMessage() the method + will return immediately after delivery and the response will be handled + asynchronously, otherwise the method will return once the reply has been + delivered or after a set timeout. + The global \a be_app_messenger pointer targets the main message loop of \a be_app is automatically initialized for you when you create a BApplication object, you can use it wherever a BMessenger is called for. @@ -88,7 +93,7 @@ \param handler The target handler. May be \c NULL. \param looper The target looper. May be \c NULL. \param _result An optional pointer to a pre-allocated status_t into which - the result of the initialization is written. + the result of the initialization is written. \since BeOS R3 */ @@ -206,8 +211,9 @@ /*! \fn status_t BMessenger::SendMessage(uint32 command, BHandler* replyTo) const - \brief Delivers a BMessage with a \c what parameter set to \a command - synchronously to the messenger's target, without waiting for a reply. + \brief Delivers a BMessage with \a command \c what identifier to the + messenger's target. A response may be sent to the \a replyTo handler + asynchronously. If the target's message port is full, the method waits indefinitely, until space becomes available in the port. After delivery the method returns @@ -230,8 +236,8 @@ /*! \fn status_t BMessenger::SendMessage(BMessage* message, BHandler* replyTo, bigtime_t timeout) const - \brief Delivers a BMessage synchronously to the messenger's target, - without waiting for a reply. + \brief Delivers a \a message to the messenger's target. A response message + may be sent back to the \a replyTo handler asynchronously. A copy of the supplied message is sent and the caller retains ownership of \a message. @@ -241,10 +247,13 @@ first). After delivery the method returns immediately. It does not wait until the target processes the message or even sends a reply. + This method does not return by default until the message has been delivered. + You can set a delivery \a timeout in microseconds. + \param message The message to be sent. - \param replyTo The handler to which a reply to the message shall be sent. + \param replyTo The handler for a response message to be sent. May be \c NULL. - \param timeout A timeout for the delivery of the message. + \param timeout The message delivery timeout in microseconds. (optional) \return A status code, \c B_OK on success or an error code otherwise. \retval B_OK Everything went fine. @@ -262,8 +271,8 @@ /*! \fn status_t BMessenger::SendMessage(BMessage* message, BMessenger replyTo, bigtime_t timeout) const - \brief Delivers a BMessage synchronously to the messenger's target, - without waiting for a reply. + \brief Delivers a \a message to the messenger's target. A response message + may be sent back to the \a replyTo messenger's target asynchronously. A copy of the supplied message is sent and the caller retains ownership of \a message. @@ -273,9 +282,12 @@ first). After delivery the method returns immediately. It does not wait until the target processes the message or even sends a reply. + This method does not return by default until the message has been delivered. + You can set a delivery \a timeout in microseconds. + \param message The message to be sent. - \param replyTo A messenger specifying the target for a reply to \a message. - \param timeout A timeout for the delivery of the message. + \param replyTo A messenger specifying the target for a response message. + \param timeout The message delivery timeout in microseconds. (optional) \return A status code, \c B_OK on success or an error code otherwise. \retval B_OK Everything went fine. @@ -292,16 +304,16 @@ /*! \fn status_t BMessenger::SendMessage(uint32 command, BMessage* reply) const - \brief Delivers a BMessage with a \c what parameter set to \a command - synchronously to the messenger's target and waits for a reply. + \brief Delivers a BMessage with \a command \c what identifier to the + messenger's target and waits for a \a reply BMessage synchronously. The method does wait for a reply. The reply message is copied into \a reply. If the target doesn't send a reply, the \c what field of \a reply is set to \c B_NO_REPLY. \param command The what field of the message to deliver. - \param reply A pointer to a pre-allocated BMessage into which the reply - message will be copied. + \param reply A pointer to a pre-allocated BMessage object which the reply + message will be copied into. \return A status code, \c B_OK on success or an error code otherwise. \retval B_OK Everything went fine. @@ -316,8 +328,8 @@ /*! \fn status_t BMessenger::SendMessage(BMessage* message, BMessage* reply, bigtime_t deliveryTimeout, bigtime_t replyTimeout) const - \brief Delivers a BMessage synchronously to the messenger's target and - waits for a reply. + \brief Delivers a \a message to the messenger's target and waits for a + \a reply to come back synchronously. A copy of the supplied message is sent and the caller retains ownership of \a message. @@ -326,11 +338,16 @@ \a reply. If the target doesn't send a reply or if a reply timeout occurs, the \c what field of \a reply is set to \c B_NO_REPLY. + This method does not return by default until the message has been delivered + and the reply has come back. You can set a \a deliveryTimeout and a + \a replyTimeout in microseconds. + \param message The message to be sent. - \param reply A pointer to a pre-allocated BMessage into which the reply - message will be copied. - \param deliveryTimeout A timeout for the delivery of the message. - \param replyTimeout A timeout for waiting for the reply. + \param reply A pointer to a pre-allocated BMessage which the reply + message will be copied into. + \param deliveryTimeout The message delivery timeout in microseconds. + (optional) + \param replyTimeout The reply message timeout in microseconds. (optional) \return A status code, \c B_OK on success or an error code otherwise. \retval B_OK Everything went fine.