/*
* "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.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* - Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
* - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* - Neither the name of the Technische Universitat Berlin nor the names
* of its contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
* TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
* OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
* OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
* USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
*/
/**
* Please refer to TEP 108 for more information about this interface and its
* intended use.
*
* The Resource interface can be used to gain access to
* shared resources. It is always offered as a parameterized
* interface, and its users gain access to the resource through some
* predefined arbitration policy.
*
* @author Kevin Klues (klueska@cs.wustl.edu)
* @version $Revision: 1.5 $
* @date $Date: 2007/04/15 20:05:03 $
*/
interface Resource {
/**
* 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.
* 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 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.
*/
event void granted();
/**
* 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
*/
async command bool isOwner();
}
