[haiku-commits] Change in haiku[master]: API Docs: Clarify BLooper::PostMessage and BMessenger::SendMessage

  • From: Gerrit <review@xxxxxxxxxxxxxxxxxxx>
  • To: waddlesplash <waddlesplash@xxxxxxxxx>, haiku-commits@xxxxxxxxxxxxx
  • Date: Sat, 1 Feb 2020 02:59:14 +0000

From John Scipione <jscipione@xxxxxxxxx>:

John Scipione has uploaded this change for review. ( 
https://review.haiku-os.org/c/haiku/+/2177 ;)


Change subject: API Docs: Clarify BLooper::PostMessage and 
BMessenger::SendMessage
......................................................................

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.
---
M docs/user/app/Looper.dox
M docs/user/app/Messenger.dox
2 files changed, 42 insertions(+), 26 deletions(-)



  git pull ssh://git.haiku-os.org:22/haiku refs/changes/77/2177/1

diff --git a/docs/user/app/Looper.dox b/docs/user/app/Looper.dox
index 482c0f9..d04063d 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 100fab7..461bb44 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 and the response will be handled asynchronously,
+       otherwise the method will return once the message 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 message 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 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 to which a response message shall be sent.
               May be \c NULL.
-       \param timeout A timeout for the delivery of the message.
+       \param timeout \a message delivery \a 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 may 
be sent
+              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 \a message delivery \a 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 message synchronously.

        A copy of the supplied message is sent and the caller retains ownership
        of \a message.
@@ -326,11 +338,15 @@
        \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.
+       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 deliveryTimeout \a message delivery timeout in microseconds.
+              (optional)
+       \param replyTimeout \a 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.

--
To view, visit https://review.haiku-os.org/c/haiku/+/2177
To unsubscribe, or for help writing mail filters, visit 
https://review.haiku-os.org/settings

Gerrit-Project: haiku
Gerrit-Branch: master
Gerrit-Change-Id: Ifc6a15134d4f0bed27fe3bed1f5c36c91f712d78
Gerrit-Change-Number: 2177
Gerrit-PatchSet: 1
Gerrit-Owner: John Scipione <jscipione@xxxxxxxxx>
Gerrit-MessageType: newchange

Other related posts: