Sifteo::BluetoothQueue< tCapacity > Struct Template Reference

A memory buffer which holds a queue of Bluetooth packets. More...

#include <sifteo/bluetooth.h>

Public Member Functions
void	clear ()
	Initializes this queue's header, and marks it as empty.
void	commit ()
	Finish writing a packet that was started with reserve() More...
unsigned	count () const
	How many packets are sitting in the queue right now? More...
const BluetoothPacket &	peek () const
	Access the oldest queued packet without copying it. More...
void	pop ()
	Dequeue the oldest packet. More...
void	read (BluetoothPacket &buffer)
	Read the oldest queued packet into a provided buffer. More...
unsigned	readAvailable () const
	How many packets are available to read from this queue right now?
BluetoothPacket &	reserve ()
	Access a buffer slot where a new packet can be written. More...
void	write (const BluetoothPacket &buffer)
	Copy a new packet into the queue, from a provided buffer. More...
unsigned	writeAvailable () const
	How many free buffers are available for writing right now?

Detailed Description

template<unsigned tCapacity>
struct Sifteo::BluetoothQueue< tCapacity >

A memory buffer which holds a queue of Bluetooth packets.

This is a FIFO buffer which holds packets that the game has created but is waiting to transmit, or packets which have been received by the system but not yet processed by the game.

This is a single-producer single-consumer lock-free queue. Typically your application is either a producer or a consumer, communicating via this queue with system software that runs in the background.

BluetoothQueues are templatized by buffer size. The system supports buffers with between 1 and 255 packets of capacity. You can pick a buffer size based on how many packets you expect may arrive between each opportunity you have to check on the queue.

Member Function Documentation

template<unsigned tCapacity>

void Sifteo::BluetoothQueue< tCapacity >::commit ( )

inline

Finish writing a packet that was started with reserve()

When this function finishes, the new packet will be visible to consumers on this queue.

template<unsigned tCapacity>

unsigned Sifteo::BluetoothQueue< tCapacity >::count ( ) const

inline

How many packets are sitting in the queue right now?

Note that the system and your application may be updating the queue concurrently. This is a single-producer single-consumer lock-free FIFO. If you're writing to the queue, you can be sure that the number of packets in the queue won't increase without your knowledge. Likewise, if you're the one reading from the queue, you can be sure that the number of packets won't decrease without your knowledge.

template<unsigned tCapacity>

const BluetoothPacket& Sifteo::BluetoothQueue< tCapacity >::peek ( ) const

inline

Access the oldest queued packet without copying it.

Must only be called if readAvailable() returns a nonzero value. If no packets are available, try again later or use an Event to get notified when Bluetooth data arrives.

This returns a reference to the oldest queued packet in the buffer. This can be used to inspect a packet before read()'ing it, or as a zero-copy alternative to read().

template<unsigned tCapacity>

void Sifteo::BluetoothQueue< tCapacity >::pop ( )

inline

Dequeue the oldest packet.

This can be called after peek() to remove the packet from our queue. Must only be called if readAvailable() returns a nonzero value.

template<unsigned tCapacity>

void Sifteo::BluetoothQueue< tCapacity >::read ( BluetoothPacket &  buffer )

inline

Read the oldest queued packet into a provided buffer.

Must only be called if readAvailable() returns a nonzero value. If no packets are available, try again later or use an Event to get notified when Bluetooth data arrives.

This function copies the data. To read data without copying, use peek() and pop().

template<unsigned tCapacity>

BluetoothPacket& Sifteo::BluetoothQueue< tCapacity >::reserve ( )

inline

Access a buffer slot where a new packet can be written.

Must only be calld if writeAvailable() returns a nonzero value. If there's no space in the buffer, try again later or use an Event to get notified when more space is available.

This "reserves" space for a new packet, and returns a reference to that space. This doesn't actually affect the state of the queue until commit(), at which point the written packet becomes visible to consumers.

template<unsigned tCapacity>

void Sifteo::BluetoothQueue< tCapacity >::write ( const BluetoothPacket &  buffer )

inline

Copy a new packet into the queue, from a provided buffer.

Must only be called if writeAvailable() returns a nonzero value. If there's no space in the buffer, try again later or use an Event to get notified when more space is available.

This function copies the data. To write data without copying, use reserve() and commit().

---

The documentation for this struct was generated from the following file:

• bluetooth.h