X-Git-Url: https://oss.titaniummirror.com/gitweb/?a=blobdiff_plain;f=tos%2Finterfaces%2FResource.nc;h=09c847f5c1e22610e8cb5d81b1b59d97950f9770;hb=ad7a3b0fbb975e842df9fabf7b77ac4ebf3b4e77;hp=79aae166aea150cc09cb1c430590938221eef7e0;hpb=1ba974b83d19fc41bf80acd52726f36f7f1df297;p=tinyos-2.x.git
diff --git a/tos/interfaces/Resource.nc b/tos/interfaces/Resource.nc
index 79aae166..09c847f5 100644
--- 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.
@@ -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.
- * 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.
+ * 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
+ * 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
+ * release
before receiving a granted
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
- * FALSE It is not the owner
+ * FALSE It is not the owner
*/
async command bool isOwner();
}