Update tos-bsl for win32 python

[tinyos-2.x.git] / tos / interfaces / Resource.nc

diff --git a/tos/interfaces/Resource.nc b/tos/interfaces/Resource.nc
index 79aae166aea150cc09cb1c430590938221eef7e0..09c847f5c1e22610e8cb5d81b1b59d97950f9770 100644 (file)
--- a/tos/interfaces/Resource.nc
+++ b/tos/interfaces/Resource.nc
@@ -50,13 +50,6 @@
  *
  */
  
-/*
- * - Revision -------------------------------------------------------------
- * $Revision$
- * $Date$ 
- * ======================================================================== 
- */
- 
 /**
  * Please refer to TEP 108 for more information about this interface and its
  * intended use.<br><br>
@@ -67,6 +60,8 @@
  * predefined arbitration policy.
  *
  * @author Kevin Klues (klueska@cs.wustl.edu)
+ * @version $Revision$
+ * @date $Date$
  */
 
 interface Resource {
@@ -81,32 +76,44 @@ interface Resource {
    *               granted event is pending
    */
   async command error_t request();
-   
+
   /**
-   * Request immediate access to a shared resource. You must call 
-   * release() when you are done with it.
-   *
-   * @return SUCCESS You now have cotnrol of the resource.<br>
-   *         EBUSY The resource is busy.  You must try again later
-   */
+  * Request immediate access to a shared resource. You must call release()
+  * when you are done with it.
+  *
+  * @return SUCCESS When a request has been accepted. <br>
+  *            FAIL The request cannot be fulfilled
+  */
   async command error_t immediateRequest();
 
   /**
-   * You are now in control of the resource. Note that this event
-   * is NOT signaled when immediateRequest() succeeds.
+   * You are now in control of the resource.
    */
   event void granted();
    
   /**
-   * Release a shared resource you previously acquired.
-   */
-  async command void release();
+  * Release a shared resource you previously acquired.  
+  *
+  * @return SUCCESS The resource has been released <br>
+  *         FAIL You tried to release but you are not the
+  *              owner of the resource 
+  *
+  * @note This command should never be called between putting in a request       
+  *       and waiting for a granted event.  Doing so will result in a
+  *       potential race condition.  There are ways to guarantee that no
+  *       race will occur, but they are clumsy and overly complicated.
+  *       Since it doesn't logically make since to be calling
+  *       <code>release</code> before receiving a <code>granted</code> event, 
+  *       we have opted to keep thing simple and warn you about the potential 
+  *       race.
+  */
+  async command error_t release();
 
   /**
    *  Check if the user of this interface is the current
    *  owner of the Resource
    *  @return TRUE  It is the owner <br>
-   *          FALSE It is not the owner
+   *             FALSE It is not the owner
    */
   async command bool isOwner();
 }