Sifteo::UsbQueue< tCapacity > Struct Template Reference

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

#include <sifteo/usb.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...
bool	empty () const
	Is the queue empty?
bool	full () const
	Is the queue full?
const UsbPacket &	peek () const
	Access the oldest queued packet without copying it. More...
void	pop ()
	Dequeue the oldest packet. More...
void	read (UsbPacket &buffer)
	Read the oldest queued packet into a provided buffer. More...
UsbPacket &	reserve ()
	Access a buffer slot where a new packet can be written. More...
void	write (const UsbPacket &buffer)
	Copy a new packet into the queue, from a provided buffer. More...

Detailed Description

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

A memory buffer which holds a queue of USB 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.

UsbQueues 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.

Template Parameters

tCapacity

The maximum number of packets this queue can buffer.

Member Function Documentation

template<unsigned tCapacity>

void Sifteo::UsbQueue< 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>

const UsbPacket& Sifteo::UsbQueue< 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 USB 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::UsbQueue< 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::UsbQueue< tCapacity >::read ( UsbPacket &  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 USB data arrives.

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

template<unsigned tCapacity>

UsbPacket& Sifteo::UsbQueue< 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::UsbQueue< tCapacity >::write ( const UsbPacket &  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:

• usb.h