Merge over into the trunk.

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

diff --git a/tos/interfaces/ResourceController.nc b/tos/interfaces/ResourceController.nc
index 048fc69784b41ff677c13792c401950683a86afc..085c5c24a3b5d3d3390fcb870b3a9c7459a177e2 100644 (file)
--- a/tos/interfaces/ResourceController.nc
+++ b/tos/interfaces/ResourceController.nc
@@ -1,27 +1,5 @@
 /*
- * "Copyright (c) 2005 Washington University in St. Louis.
- * All rights reserved.
- *
- * Permission to use, copy, modify, and distribute this software and its
- * documentation for any purpose, without fee, and without written agreement is
- * hereby granted, provided that the above copyright notice, the following
- * two paragraphs and the author appear in all copies of this software.
- *
- * IN NO EVENT SHALL WASHINGTON UNIVERSITY IN ST. LOUIS BE LIABLE TO ANY PARTY 
- * FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING 
- * OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF WASHINGTON 
- * UNIVERSITY IN ST. LOUIS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * WASHINGTON UNIVERSITY IN ST. LOUIS SPECIFICALLY DISCLAIMS ANY WARRANTIES,
- * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
- * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
- * ON AN "AS IS" BASIS, AND WASHINGTON UNIVERSITY IN ST. LOUIS HAS NO 
- * OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
- * MODIFICATIONS."
- */
- 
-/*
- * Copyright (c) 2004, Technische Universitat Berlin
+ * Copyright (c) 2005, Technische Universitaet Berlin
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -50,64 +28,37 @@
  *
  */
  
-/*
- * - Revision -------------------------------------------------------------
- * $Revision$
- * $Date$ 
- * ======================================================================== 
- */
- 
 /**
  * Please refer to TEP 108 for more information about this interface and its
  * intended use.<br><br>
  *
- * This interface is an extension of the Resource interface.  It has all of the
- * commands and events present in the Resource interface, along with two additional
- * events.  These events allow the user of this interface to be notified whenever
- * someone requests the use of a resource or whenever the resource becomes idle.
- * One could use this interface to control access to a resource by always
- * taking control of a resource whenever it has gone idle and deciding when to
- * release it based on requests from other users.
- *
- * @author Kevin Klues (klues@tkn.tu-berlin.de)
+ * @author Kevin Klues (klues@tkn.tu-berlin.edu)
+ * @version $Revision$
+ * @date $Date$ 
  */
 
 interface ResourceController {
   /**
-   * Request access to a shared resource. You must call release()
-   * when you are done with it.
-   *
-   * @return SUCCESS When a request has been accepted. The granted()
-   *                 event will be signaled once you have control of the
-   *                 resource.<br>
-   *         EBUSY You have already requested this resource and a
-   *               granted event is pending
+   * Event sent to the resource controller giving it control whenever a resource
+   * goes idle. That is to say, whenever no one currently owns the resource,
+   * and there are no more pending requests
   */
-  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
-  */
-  async command error_t immediateRequest();
+  async event void granted();
 
   /**
-  * You are now in control of the resource. Note that this event
-  * is NOT signaled when immediateRequest() succeeds.
-  */
-  event void granted();
-   
-  /**
-  * Release a shared resource you previously acquired.
+  * Release control of the resource
+  *
+  * @return SUCCESS The resource has been released and pending requests
+  *                 can resume. <br>
+  *             FAIL You tried to release but you are not the
+  *                  owner of the resource
   */
-  async command void release();
+  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
    */
@@ -116,15 +67,16 @@ interface ResourceController {
   /**
    * This event is signalled whenever the user of this interface
    * currently has control of the resource, and another user requests
-   * it.  You may want to consider releasing a resource based on this
-   * event
+   * it through the Resource.request() command. You may want to
+   * consider releasing a resource based on this event
    */
   async event void requested();
 
   /**
-   * Event sent to the resource controller whenever a resource goes idle.
-   * That is to say, whenever no one currently owns the resource, and there
-   * are no more pending requests
-   */
-  async event void idle(); 
+  * This event is signalled whenever the user of this interface
+  * currently has control of the resource, and another user requests
+  * it through the Resource.immediateRequest() command. You may
+  * want to consider releasing a resource based on this event
+  */
+  async event void immediateRequested();
 }