Difference between revisions of "GQUEUE"
(Created page with "The GQUEUE modules does provide queues and buffers. == Buffers == A pool of buffers can be allocated using <code>gfxBufferAlloc(num, size)</code> where ''num'' is the number...") |
(→API reference) |
||
| (14 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | The GQUEUE modules | + | The GQUEUE modules provides implementations of different queues and buffers. |
| + | |||
| + | == API reference == | ||
| + | The API reference of the GQUEUE module can be found [http://api.ugfx.org/group___g_q_u_e_u_e.html here]. | ||
== Buffers == | == Buffers == | ||
| − | A pool of buffers can be allocated using <code>gfxBufferAlloc(num, size)</code> where ''num'' is the number of buffers and ''size'' the size per buffer. | + | Buffers are used to pass data from one module to another. For example, buffers are used to read an audio file from an SD-Card using the [[GFILE]] module and output it using the [[GAUDIO]] module. |
| + | |||
| + | === Allocation === | ||
| + | A pool of buffers can be allocated using <code>gfxBufferAlloc(num, size)</code> where ''num'' is the number of buffers and ''size'' the size per buffer. The created buffer pool is global. It is not possible to have more than one buffer pool. | ||
| + | |||
| + | Memory once dedicated to become a buffer cannot be freed anymore. Therefore, the number and size of the buffers allocated should be chosen carefully. | ||
| + | |||
| + | === Handling === | ||
| + | <code>gfxBufferGet()</code> will return a pointer to a free buffer in the buffer pool (if any). The buffer is marked as used until it has been released using <code>gfxBufferRelease()</code>. | ||
| + | Note that some modules like the [[GAUDIO]] module that take a buffer as a parameter usually release the buffer automatically. | ||
| + | |||
| + | As <code>gfxBufferGet()</code> takes a timeout parameter, this function polls until either a free buffer is available or the timeout is exceeded. To avoid this, <code>gfxBufferIsAvailable()</code> can be used to check if there is a free buffer before hand. | ||
| + | |||
| + | === Example === | ||
| + | The [[GAUDIO]] play back demo shows how to use buffers. | ||
== Queues == | == Queues == | ||
| − | Although the queues provided by the GQUEUE module are mainly used internally, these features are still accessible for the user. | + | Although the queues provided by the GQUEUE module are mainly used internally, these features are still accessible for the user. The user can use the queue by creating a struct and using ''gfxQueueASyncItem'' as the first struct member. |
| + | |||
| + | === Types === | ||
| + | There are three types of queues available: | ||
| + | {| class="wikitable" | ||
| + | |- | ||
| + | ! Queue Type !! Description | ||
| + | |- | ||
| + | | ASync || Fully asynchronous queue. Queue operations do never block | ||
| + | |- | ||
| + | | GSync || ''Get'' synchronous queue. The ''put'' operations are still asynchronous. | ||
| + | |- | ||
| + | | FSync || Fully synchronous queue. Both, the ''put'' and the ''get'' operations are synchronous. | ||
| + | |} | ||
| + | |||
| + | === Operations === | ||
| + | Although there are three types of queues, the API is fully compatible between them. Only the function name changes (''ASync'', ''GSync'', ''FSync''). | ||
| + | |||
| + | The following queue operations are available: | ||
| + | * Init | ||
| + | * Deinit | ||
| + | * Put | ||
| + | * Push | ||
| + | * Insert | ||
| + | * Get | ||
| + | * Pop | ||
| + | * Peek | ||
| + | * Next | ||
| + | * Remove | ||
| + | * IsIn | ||
| + | * IsEmpty | ||
| + | Please refer to the [[#API_reference|API reference]] for further information. | ||
| − | [[Category: | + | [[Category:Module]] |
Latest revision as of 15:51, 4 February 2016
The GQUEUE modules provides implementations of different queues and buffers.
Contents
API reference
The API reference of the GQUEUE module can be found here.
Buffers
Buffers are used to pass data from one module to another. For example, buffers are used to read an audio file from an SD-Card using the GFILE module and output it using the GAUDIO module.
Allocation
A pool of buffers can be allocated using gfxBufferAlloc(num, size) where num is the number of buffers and size the size per buffer. The created buffer pool is global. It is not possible to have more than one buffer pool.
Memory once dedicated to become a buffer cannot be freed anymore. Therefore, the number and size of the buffers allocated should be chosen carefully.
Handling
gfxBufferGet() will return a pointer to a free buffer in the buffer pool (if any). The buffer is marked as used until it has been released using gfxBufferRelease().
Note that some modules like the GAUDIO module that take a buffer as a parameter usually release the buffer automatically.
As gfxBufferGet() takes a timeout parameter, this function polls until either a free buffer is available or the timeout is exceeded. To avoid this, gfxBufferIsAvailable() can be used to check if there is a free buffer before hand.
Example
The GAUDIO play back demo shows how to use buffers.
Queues
Although the queues provided by the GQUEUE module are mainly used internally, these features are still accessible for the user. The user can use the queue by creating a struct and using gfxQueueASyncItem as the first struct member.
Types
There are three types of queues available:
| Queue Type | Description |
|---|---|
| ASync | Fully asynchronous queue. Queue operations do never block |
| GSync | Get synchronous queue. The put operations are still asynchronous. |
| FSync | Fully synchronous queue. Both, the put and the get operations are synchronous. |
Operations
Although there are three types of queues, the API is fully compatible between them. Only the function name changes (ASync, GSync, FSync).
The following queue operations are available:
- Init
- Deinit
- Put
- Push
- Insert
- Get
- Pop
- Peek
- Next
- Remove
- IsIn
- IsEmpty
Please refer to the API reference for further information.
