dbbuffer.nc

用于传感器网络的节点操作系统 TinyOS 结构设计非常有意思

/*									tab:4
 *
 *
 * "Copyright (c) 2000-2002 The Regents of the University  of California.  
 * 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 THE UNIVERSITY OF CALIFORNIA 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 THE UNIVERSITY OF
 * CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * 
 * THE UNIVERSITY OF CALIFORNIA 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 THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS."
 *
 */
/*									tab:4
 *  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.  By
 *  downloading, copying, installing or using the software you agree to
 *  this license.  If you do not agree to this license, do not download,
 *  install, copy or use the software.
 *
 *  Intel Open Source License 
 *
 *  Copyright (c) 2002 Intel Corporation 
 *  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 Intel Corporation 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 INTEL OR ITS
 *  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.
 * 
 * 
 */
includes TinyDB;
includes DBBuffer;

/** The DBBuffer interface provides a place for queries to output their results
   to or fetch results from.
  <p>
   Buffers can be in RAM or simply drain out to the network.  In the case
   of RAM buffers, they have a fixed (preallocated) number of rows that
   are recycled according to some eviction policy.  Radio buffers have a
   single logical row that is written out via a RadioQueue interface.
   @author Sam Madden ([e-mail])
   
*/

interface DBBuffer {
  /** Enqueue a result into the specified buffer 
   @param bufferId The buffer to enqueue into
   @param r The result to enqueue
   @param pending (On return) Set to TRUE if the enqueue is still pending (completion singalled via  a putComplete event if TRUE)
   @param pq The query corresponding to this result
   @return err_OutOfMemory if the buffer is full
   @return err_ResultBufferBusy If other buffer requests are currently outstanding
     
  */
    command TinyDBError enqueue(uint8_t bufferId, QueryResultPtr r, bool *pending, ParsedQueryPtr pq);

    /** Deallocate (without returning) the first item at the top of the queue.  
	To read the first item, use peek(), and call pop() when it is no longer needed
	@return err_NoMoreResults if no results are available
    */
    command TinyDBError pop(uint8_t bufferId);
    
    /** Copy the top most result in the specified buffer into buf

     if *pending is true on return, the result will not be available until getComplete 
     is signalled,  Otherwise, the result is available immediately. No
     further calls to dequeue/peek/getResult are allowed until putComplete is signalled.
     <p>
     Note that this routine may return a QueryResult that contains pointers into DBBuffer-local
     data structures which will be deallocated as soon as pop() is called.

     @return err_NoMoreResults if no results are available

    */
    command TinyDBError peek(uint8_t bufferId, QueryResult *buf, bool *pending);

    
  /* Copy the nth result in the specified buffer into buf
     <p>
     If *pending is TRUE on return, the result will not be available until getComplete 
     is signalled,  Otherwise, the result is available immediately. No
     further calls to dequeue/peek/getResult are allowed until putComplete is signalled.
     <p>
     Note that this routine may return a QueryResult that contains pointers into DBBuffer-local
     data structures which will be deallocated the fetched item is pop'ed() from the queue.
     
     @return err_ResultBufferBusy If other buffer requests are currently outstanding
     @return err_NoMoreResults  if idx > getSize() or if buffer[idx] is empty (unset)
    */
    command TinyDBError getResult(uint8_t bufferId, uint16_t idx, QueryResult *buf, bool *pending);

    /** Allocate the specified buffer with the specified size 
       sizes is an array of sizes of each field, with one entry per field

       Signals allocComplete when allocation is complete if *pending is true on return
       Data is buffer type specific data

       If *pending is true on return, the result will not be available until getComplete 
       is signalled,  Otherwise, the result is available immediately. No
       further calls to dequeue/peek/getResult are allowed until putComplete is signalled.

       @return err_UnsupportedPolicy if the specified policy can't be applied
       @return err_ResultBufferBusy If other buffer requests are currently outstanding
    */
    command TinyDBError alloc(uint8_t bufferId, BufferType type, uint16_t size, BufferPolicy policy,
			      ParsedQuery *schema, bool *pending, long data);

    /** @return the number of rows in the specified buffer */
    command uint16_t maxSize(uint8_t bufferId );
    
    /** @return the number of used rows in the buffer */
    command TinyDBError size(uint8_t bufferId, uint16_t *size);
    
    /** @return the schema of the results in the specified buffer */
    command ParsedQuery **getSchema(uint8_t bufferId );
    
    /** @param bufferId (on return) An unused buffer id
	@return the next unused buffer id (in bufferId), or err_OutOfMemory, if no mo buffers are available 
    */
    command TinyDBError nextUnusedBuffer(uint8_t *bufferId);
  
    /**	
	Looks up the buffer id that corresponds to the specified query id
	in bufferId <p>

	@param qid The query id to lookup
	@param bufferId (on return) The id of the buffer corresponding to qid
	@return err_InvalidIndex if no such buffer exists 	
    */
  command TinyDBError qidToBuffer(uint8_t qid, uint8_t *bufferId);


  /** Signalled when a new result is enqueued in the specified buffer*/
  event result_t resultReady(uint8_t bufferId );

  /** Signalled when a result is dequeued from the specified buffer*/
  event result_t getNext(uint8_t bufferId );

  /** Signalled when allocation is complete for the specified buffer*/
  event result_t allocComplete(uint8_t bufferId, TinyDBError result);

  /** Signalled when a get is complete */
  event result_t getComplete(uint8_t bufferId, QueryResult *buf);

  /** Signalled when a put is complete */
  event result_t putComplete(uint8_t bufferId, QueryResult *buf, TinyDBError result);

}