Interface: DBBuffer

The DBBuffer interface provides a place for queries to output their results to or fetch results from.

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 (madden@cs.berkeley.edu)

Components providing this interface:: tos.lib.TinyDB.DBBufferC

Components requiring this interface:: tos.lib.TinyDB.TupleRouterM

Commands

TinyDBError enqueue(uint8_t bufferId, QueryResultPtr r, bool *pending, ParsedQueryPtr pq) Enqueue a result into the specified buffer

Parameters:	bufferId - The buffer to enqueue into r - The result to enqueue pending - (On return) Set to TRUE if the enqueue is still pending (completion singalled via a putComplete event if TRUE) pq - The query corresponding to this result
Returns:	err_OutOfMemory if the buffer is full
	err_ResultBufferBusy If other buffer requests are currently outstanding

TinyDBError pop (uint8_t bufferId) Deallocate (without returning) the first item at the top of the queue.
TinyDBError peek (uint8_t bufferId, QueryResult *buf, bool *pending) 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.
TinyDBError getResult(uint8_t bufferId, uint16_t idx, QueryResult *buf, bool *pending)
TinyDBError alloc (uint8_t bufferId, BufferType type, uint16_t size, BufferPolicy policy, ParsedQuery *schema, bool *pending, long data) 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.
uint16_t maxSize(uint8_t bufferId)

Returns: the number of rows in the specified buffer
TinyDBError size(uint8_t bufferId, uint16_t *size)

Returns: the number of used rows in the buffer
ParsedQuery getSchema(uint8_t bufferId)

Returns: the schema of the results in the specified buffer
TinyDBError nextUnusedBuffer(uint8_t *bufferId)

Parameters:
bufferId - (on return) An unused buffer id

Returns: the next unused buffer id (in bufferId), or err_OutOfMemory, if no mo buffers are available
TinyDBError qidToBuffer(uint8_t qid, uint8_t *bufferId) Looks up the buffer id that corresponds to the specified query id in bufferId

Parameters:
qid - The query id to lookup
bufferId - (on return) The id of the buffer corresponding to qid

Returns: err_InvalidIndex if no such buffer exists

Events

result_t resultReady(uint8_t bufferId) Signalled when a new result is enqueued in the specified buffer
result_t getNext(uint8_t bufferId) Signalled when a result is dequeued from the specified buffer
result_t allocComplete(uint8_t bufferId, TinyDBError result) Signalled when allocation is complete for the specified buffer
result_t getComplete(uint8_t bufferId, QueryResult *buf) Signalled when a get is complete
result_t putComplete(uint8_t bufferId, QueryResult *buf, TinyDBError result) Signalled when a put is complete

Commands - Details

pop

TinyDBError pop(uint8_t bufferId)

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

Returns:

err_NoMoreResults if no results are available

peek

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

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.

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.

Returns: err_NoMoreResults if no results are available

alloc

TinyDBError alloc(uint8_t bufferId, BufferType type, uint16_t size, BufferPolicy policy, ParsedQuery *schema, bool *pending, long data)

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.

Returns:	err_UnsupportedPolicy if the specified policy can't be applied
	err_ResultBufferBusy If other buffer requests are currently outstanding

Parameters:	bufferId - (on return) An unused buffer id
Returns:	the next unused buffer id (in bufferId), or err_OutOfMemory, if no mo buffers are available

Parameters:	qid - The query id to lookup bufferId - (on return) The id of the buffer corresponding to qid
Returns:	err_InvalidIndex if no such buffer exists