[haiku-commits] haiku: hrev45339 - docs/user/storage

From: jscipione@xxxxxxxxx
To: haiku-commits@xxxxxxxxxxxxx
Date: Tue, 5 Mar 2013 01:25:31 +0100 (CET)
hrev45339 adds 1 changeset to branch 'master'
old head: afecfa9ca86a2431c6ff990e6ccb24e3f807699d
new head: 880e147bd97b1606c3abe7b2bde9cdd93fa1c3a2
overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=880e147+%5Eafecfa9

----------------------------------------------------------------------------

880e147: Node Monitor documentation updates to stop_watching().
  
  * Add a note to stop_watching() about the asynchronous nature of node
    monitoring and its consequences.
  * Also update the breif description and parameters of stop_watching().
  * Detail the return values of stop_watching() a bit better.
  * Add a note (an \attention actually) to B_STOP_WATCHING flag.
  * Fix a spelling mistake and other minor fixes.

                                     [ John Scipione <jscipione@xxxxxxxxx> ]

----------------------------------------------------------------------------

Revision:    hrev45339
Commit:      880e147bd97b1606c3abe7b2bde9cdd93fa1c3a2
URL:         http://cgit.haiku-os.org/haiku/commit/?id=880e147
Author:      John Scipione <jscipione@xxxxxxxxx>
Date:        Tue Mar  5 00:24:31 2013 UTC

----------------------------------------------------------------------------

1 file changed, 35 insertions(+), 11 deletions(-)
docs/user/storage/NodeMonitor.dox | 46 ++++++++++++++++++++++++++---------

----------------------------------------------------------------------------

diff --git a/docs/user/storage/NodeMonitor.dox 
b/docs/user/storage/NodeMonitor.dox
index 7cc288c..3df7e78 100644
--- a/docs/user/storage/NodeMonitor.dox
+++ b/docs/user/storage/NodeMonitor.dox
@@ -35,6 +35,9 @@
        \var B_STOP_WATCHING
 
        Flag for watch_node(). Unsubscribe from watching a node.
+
+       \attention \c B_STOP_WATCHING does not apply to volume watching, you 
must
+                  call stop_watching() instead.
 */
 
 
@@ -329,13 +332,13 @@
        - \c B_WATCH_ALL
        - \c B_WATCH_MOUNT
 
-       Note, that the latter two cases are not mutual exclusive, i.e. mount and
+       Note that the latter two cases are not mutual exclusive, i.e. mount and
        node watching can be requested with a single call.
 
        \param node node_ref referring to the node to be watched. May be \c 
NULL,
               if only mount watching is requested.
        \param flags Flags indicating the actions to be performed.
-       \param target Messenger referring to the target. Must be valid.
+       \param target BMessenger object referring to the \a target.
 
        \return \c B_OK if everything went fine, an error code otherwise.
 */
@@ -368,7 +371,7 @@
        - \c B_WATCH_ALL
        - \c B_WATCH_MOUNT
 
-       Note, that the latter two cases are not mutual exlusive, i.e. mount and
+       Note that the latter two cases are not mutual exclusive, i.e. mount and
        node watching can be requested with a single call.
 
        \param node node_ref referring to the node to be watched. May be \c 
NULL,
@@ -387,20 +390,41 @@
        \fn status_t stop_watching(BMessenger target)
        \brief Unsubscribes \a target from node and mount monitoring.
 
-       \param target Messenger referring to the target. Must be valid.
+       You may still receive notification messages after calling 
stop_watching()
+       because while node monitoring is asynchronous and all changes are 
atomic,
+       message sending is not atomic so there is a lag time from when you
+       stop monitoring and when the message is received in your message 
receiving
+       thread. You can check the timestamp of the message to determine if
+       it was sent after stop_watching() was called.
 
-       \return \c B_OK if everything went fine, an error code otherwise.
+       \param target BMessenger object referring to the \a target.
+
+       \return A status code.
+       \retval B_OK Stopped sending notification messages to the \a target.
+       \retval B_BAD_VALUE \a target was invalid.
+       \retval B_ENTRY_NOT_FOUND Node not found.
 */
 
 
 /*!
        \fn status_t stop_watching(const BHandler *handler, const BLooper 
*looper)
-       \brief Unsubscribes \a target from node and mount monitoring.
+       \brief Unsubscribes \a handler or \a looper target from node and mount
+              monitoring.
 
-       \param handler The target handler. May be \c NULL, if \a looper is not
-              \c NULL. Then the preferred handler of the looper is targeted.
-       \param looper The target looper. May be \c NULL, if \a handler is not
-              \c NULL. Then the handler's looper is the target looper.
+       You may still receive notification messages after calling 
stop_watching()
+       because while node monitoring is asynchronous and all changes are 
atomic,
+       message sending is not atomic so there is a lag time from when you
+       stop monitoring and when the message is received in your message 
receiving
+       thread. You can check the timestamp of the message to determine if
+       it was sent after stop_watching() was called.
 
-       \return \c B_OK if everything went fine, an error code otherwise.
+       \param handler The target handler, may be \c NULL. If \a looper is not
+              \c NULL then the looper's preferred handler is targeted.
+       \param looper The target looper, may be \c NULL. If \a handler is not
+              \c NULL then the handler's looper is targeted.
+
+       \return A status code.
+       \retval B_OK Stopped sending notification messages to the target.
+       \retval B_BAD_VALUE Target from \a handler or \a looper was invalid.
+       \retval B_ENTRY_NOT_FOUND Node not found.
 */
[haiku-commits] haiku: hrev45339 - docs/user/storage

Other related posts:
