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.ParsedQuery
tos.lib.TinyDB.Tuple
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 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 getFieldId (uint8_t bufferId, FieldPtr f, uint8_t *id) Gets the index of field f in the specified buffer.
TinyDBError getField (uint8_t bufferId, QueryResult *qr, uint8_t idx, char *resultBuf) Gets the specified field from the QueryResult produced by reading from bufferId and writes the value into resultBuf.
TinyDBError alloc (uint8_t bufferId, BufferType type, uint16_t size, BufferPolicy policy, ParsedQuery *schema, char *name, 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 getBufferId (uint8_t qid, bool isSpecial, uint8_t *bufferId) Looks up the buffer id that corresponds to the specified query id in bufferId
TinyDBError getBufferIdFromName(char *name, uint8_t *bufferId) Looks up the buffer id that corresponds to the specified name

Parameters:
name - The name of the buffer
bufferId - (on return) The id of buffer name

Returns: err_InvalidIndex if no such buffer exists
TinyDBError qidFromBufferId(uint8_t bufId, uint8_t *qid) Given a buffer id, return the query id which describes its schema
TinyDBError openBuffer(uint8_t bufIdx, bool *pending)

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, TinyDBError result) Signalled when a get is complete
result_t putComplete(uint8_t bufferId, QueryResult *buf, TinyDBError result) Signalled when a put is complete
result_t openComplete(uint8_t bufferId, TinyDBError result)

Commands - Details

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

getFieldId

TinyDBError getFieldId(uint8_t bufferId, FieldPtr f, uint8_t *id)

Gets the index of field f in the specified buffer.

Parameters:	bufferId - The bufferId (returned from getBufferId) to look for field f in f - The name of the desired field id - (On return) The index of the specified field in bufferId, if the return code == err_NoError
Returns:	err_NoError on no error, err_UnsupportedBuffer or err_InvalidIndex on failure

getField

TinyDBError getField(uint8_t bufferId, QueryResult *qr, uint8_t idx, char *resultBuf)

Gets the specified field from the QueryResult produced by reading from bufferId and writes the value into resultBuf.

Parameters:

bufferId - The bufferId (returned from getBufferId) that this is a query result for

qr - The query result (return from peek or getResult) to get the field from

idx - The index of the field to retrieve

resultBuf - The buffer to write the value of the field into

alloc

TinyDBError alloc(uint8_t bufferId, BufferType type, uint16_t size, BufferPolicy policy, ParsedQuery *schema, char *name, 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

getBufferId

TinyDBError getBufferId(uint8_t qid, bool isSpecial, 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
isSpecial - Is this a "special" (e.g. catalog buffer), or does it correspond to the results of an actual query

Returns: err_InvalidIndex if no such buffer exists

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:	name - The name of the buffer bufferId - (on return) The id of buffer name
Returns:	err_InvalidIndex if no such buffer exists

Parameters:	qid - The query id to lookup bufferId - (on return) The id of the buffer corresponding to qid isSpecial - Is this a "special" (e.g. catalog buffer), or does it correspond to the results of an actual query
Returns:	err_InvalidIndex if no such buffer exists