[Tinyos-2-commits] CVS: tinyos-2.x/tos/interfaces ResourceQueue.nc, NONE, 1.1.2.1 ResourceRequested.nc, 1.1.2.4, 1.1.2.5 Resource.nc, 1.1.2.9, 1.1.2.10 ResourceController.nc, 1.1.2.3, 1.1.2.4

Tue Aug 15 04:50:45 PDT 2006

Update of /cvsroot/tinyos/tinyos-2.x/tos/interfaces
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv2694/tos/interfaces

Modified Files:
      Tag: tinyos-2_0_devel-BRANCH
	Resource.nc ResourceController.nc 
Added Files:
      Tag: tinyos-2_0_devel-BRANCH
	ResourceQueue.nc ResourceRequested.nc 
Log Message:
Update to Resource and Power Manager stuff

--- NEW FILE: ResourceQueue.nc ---
/*
 * "Copyright (c) 2006 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."
 */

/**
 *  A queue interface for managing client ids when performing resource 
 *  arbitration. A single slot in the queue is guaranteed to each resource
 *  client, with the actual queing policy determined by the implementation
 *  of the interface.
 *
 *  @author Kevin Klues <klueska at cs.wustl.edu>
 *  @date   $Date: 2006/08/15 11:50:42 $
 */

#include "Resource.h"

interface ResourceQueue {

  /**
   * Check to see if the queue is empty.
   *
   * @return TRUE  if the queue is empty. <br>
   *         FALSE if there is at least one entry in the queue
   */
  async command bool isEmpty();

  /**
   * Check to see if a given cleint id has already been enqueued
   * and is waiting to be processed.
   *
   * @return TRUE  if the client id is in the queue. <br>
   *         FALSE if it does not
   */
  async command bool isEnqueued(resource_client_id_t id);

  /**
   * Retreive the cleint id of the next resource in the queue. 
   * If the queue is empty, the return value is undefined.
   *
   * @return The cleint id at the head of the queue.
   */
  async command resource_client_id_t dequeue();

  /**
   * Enqueue a cleint id
   *
   * @param cleintId - the cleint id to enqueue
   * @return SUCCESS if the client id was enqueued successfully <br>
   *         EBUSY   if it has already been enqueued.
   */
  async command error_t enqueue(resource_client_id_t id);
}

Index: Resource.nc
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/tos/interfaces/Resource.nc,v
retrieving revision 1.1.2.9
retrieving revision 1.1.2.10
diff -C2 -d -r1.1.2.9 -r1.1.2.10
*** Resource.nc	8 Mar 2006 02:01:47 -0000	1.1.2.9
--- Resource.nc	15 Aug 2006 11:50:42 -0000	1.1.2.10
***************
*** 51,61 ****
   */

- /*
-  * - Revision -------------------------------------------------------------
-  * $Revision$
-  * $Date$ 
-  * ======================================================================== 
-  */
-  
  /**
   * Please refer to TEP 108 for more information about this interface and its
--- 51,54 ----
***************
*** 68,71 ****
--- 61,66 ----
   *
   * @author Kevin Klues (klueska at cs.wustl.edu)
+  * @version $Revision$
+  * @date $Date$
   */

***************
*** 82,105 ****
     */
    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();

    /**
!    * 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.
!    */
!   async command void release();

    /**
--- 77,103 ----
     */
    async command error_t request();
! 
    /**
!   * 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.
     */
    event void granted();

    /**
!   * 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 
!   */
!   async command error_t release();

    /**
***************
*** 107,111 ****
     *  owner of the Resource
     *  @return TRUE  It is the owner <br>
!    *          FALSE It is not the owner
     */
    async command bool isOwner();
--- 105,109 ----
     *  owner of the Resource
     *  @return TRUE  It is the owner <br>
!    *             FALSE It is not the owner
     */
    async command bool isOwner();

Index: ResourceController.nc
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/tos/interfaces/ResourceController.nc,v
retrieving revision 1.1.2.3
retrieving revision 1.1.2.4
diff -C2 -d -r1.1.2.3 -r1.1.2.4
*** ResourceController.nc	8 Mar 2006 02:01:48 -0000	1.1.2.3
--- ResourceController.nc	15 Aug 2006 11:50:42 -0000	1.1.2.4
***************
*** 1,26 ****
  /*
!  * "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
   * All rights reserved.
   *
--- 1,4 ----
  /*
!  * Copyright (c) 2005, Technische Universitaet Berlin
   * All rights reserved.
   *
***************
*** 51,112 ****
   */

- /*
-  * - 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 at tkn.tu-berlin.de)
   */

  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
!   */
!   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();

    /**
!   * 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.
    */
!   async command void 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
--- 29,63 ----
   */

  /**
   * Please refer to TEP 108 for more information about this interface and its
   * intended use.<br><br>
   *
!  * @author Kevin Klues (klues at tkn.tu-berlin.edu)
!  * @version $Revision$
!  * @date $Date$ 
   */

  interface ResourceController {
    /**
!    * 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 event void granted();

    /**
!   * 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 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
***************
*** 117,130 ****
     * 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
     */
    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(); 
  }
--- 68,82 ----
     * This event is signalled whenever the user of this interface
     * currently has control of the resource, and another user requests
!    * it through the Resource.request() command. You may want to
!    * consider releasing a resource based on this event
     */
    async event void requested();

    /**
!   * 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();
  }