Difference between pages "r7.0.0:Function lfds700 queue bss cleanup" and "r7.0.0:Function lfds700 queue bss query"
Line 1: | Line 1: | ||
{{DISPLAYTITLE:function | {{DISPLAYTITLE:function lfds700_queue_bss_query}} | ||
==Source Files== | ==Source Files== | ||
└───liblfds700 | └───liblfds700 | ||
Line 7: | Line 7: | ||
└───src | └───src | ||
└───lfds700_queue_bounded_singleconsumer_singleproducer | └───lfds700_queue_bounded_singleconsumer_singleproducer | ||
lfds700_queue_bounded_singleconsumer_singleproducer_query.c | |||
==Enums== | |||
enum [[r7.0.0:enum lfds700_queue_bss_query|lfds700_queue_bss_query]] | |||
{ | |||
LFDS700_QUEUE_BSS_QUERY_GET_POTENTIALLY_INACCURATE_COUNT, | |||
LFDS700_QUEUE_BSS_QUERY_VALIDATE | |||
}; | |||
==Opaque Structures== | ==Opaque Structures== | ||
Line 13: | Line 20: | ||
==Prototype== | ==Prototype== | ||
void | void lfds700_queue_bss_query( struct lfds700_queue_bss_state *qbsss, | ||
enum lfds700_queue_bss_query query_type, | |||
void *query_input, | |||
void *query_output ); | |||
==Parameters== | ==Parameters== | ||
Line 19: | Line 29: | ||
: A pointer to an initialized ''struct lfds700_queue_bss_state''. | : A pointer to an initialized ''struct lfds700_queue_bss_state''. | ||
''void | ''enum lfds700_queue_bss_query query_type'' | ||
: A | : A single value from ''enum lfds700_queue_bss_query'', which indicates which query to perform. | ||
''void *query_input'' | |||
: A pointer to input data for the query, where the data varies by query; | |||
:: ''LFDS700_QUEUE_BSS_QUERY_GET_POTENTIALLY_INACCURATE_COUNT'' | |||
::: ''query_input'' is NULL. | |||
:: ''LFDS700_QUEUE_BSS_QUERY_VALIDATE'' | |||
::: ''query_input'' can be NULL, or or can be a pointer to a ''struct lfds700_misc_validation_info'', which specifies an expected min/max count, in which case validation also counts the number of elements and check they fall within the specified range. | |||
''void *query_output'' | |||
: A pointer to output store for the query, where the output varies by query; | |||
:: ''LFDS700_QUEUE_BSS_QUERY_GET_POTENTIALLY_INACCURATE_COUNT'' | |||
::: Points to a ''lfds700_pal_uint_t'', which is set to the number of elements in the queue. | |||
:: ''LFDS700_QUEUE_BSS_QUERY_VALIDATE'' | |||
::: Points to an enum ''[[r7.0.0:enum lfds700_misc_validity|lfds700_misc_validity]]'', which is set to indicate the result of the validation operation. | |||
==Notes== | ==Notes== | ||
All ''SINGLETHREADED'' queries can only be safely performed if no enqueue or dequeue operations occur while the operation runs. If enqueue or dequeue operations do occur during the execution of a ''SINGLETHREADED'' query, it is theoretically possible for the query to enter an infinite loop. Do not do this. | |||
The ''LFDS700_QUEUE_BSS_QUERY_GET_POTENTIALLY_INACCURATE_COUNT'' query is not guaranteed to be accurate. Where enqueue and dequeue operations are not guaranteed to be visible by the time the function calls return, similarly, it may be that a count will during its operation not see an element which has been enqueued, or see that an element has been dequeued. In general however it should be bang on; it's just it's not guaranteed. | |||
==Example== | ==Example== | ||
Line 32: | Line 56: | ||
==See Also== | ==See Also== | ||
* [[r7.0.0:Queue (bounded, single consumer, single producer)|Queue (bounded, single consumer, single producer)]] | * [[r7.0.0:Queue (bounded, single consumer, single producer)|Queue (bounded, single consumer, single producer)]] | ||
Latest revision as of 02:00, 30 December 2015
Source Files
└───liblfds700 ├───inc │ └───liblfds700 │ lfds700_queue_bounded_singleconsumer_singleproducer.h └───src └───lfds700_queue_bounded_singleconsumer_singleproducer lfds700_queue_bounded_singleconsumer_singleproducer_query.c
Enums
enum lfds700_queue_bss_query { LFDS700_QUEUE_BSS_QUERY_GET_POTENTIALLY_INACCURATE_COUNT, LFDS700_QUEUE_BSS_QUERY_VALIDATE };
Opaque Structures
struct lfds700_queue_bss_state;
Prototype
void lfds700_queue_bss_query( struct lfds700_queue_bss_state *qbsss, enum lfds700_queue_bss_query query_type, void *query_input, void *query_output );
Parameters
struct lfds700_queue_bss_state *qbsss
- A pointer to an initialized struct lfds700_queue_bss_state.
enum lfds700_queue_bss_query query_type
- A single value from enum lfds700_queue_bss_query, which indicates which query to perform.
void *query_input
- A pointer to input data for the query, where the data varies by query;
- LFDS700_QUEUE_BSS_QUERY_GET_POTENTIALLY_INACCURATE_COUNT
- query_input is NULL.
- LFDS700_QUEUE_BSS_QUERY_VALIDATE
- query_input can be NULL, or or can be a pointer to a struct lfds700_misc_validation_info, which specifies an expected min/max count, in which case validation also counts the number of elements and check they fall within the specified range.
- LFDS700_QUEUE_BSS_QUERY_GET_POTENTIALLY_INACCURATE_COUNT
void *query_output
- A pointer to output store for the query, where the output varies by query;
- LFDS700_QUEUE_BSS_QUERY_GET_POTENTIALLY_INACCURATE_COUNT
- Points to a lfds700_pal_uint_t, which is set to the number of elements in the queue.
- LFDS700_QUEUE_BSS_QUERY_VALIDATE
- Points to an enum lfds700_misc_validity, which is set to indicate the result of the validation operation.
- LFDS700_QUEUE_BSS_QUERY_GET_POTENTIALLY_INACCURATE_COUNT
Notes
All SINGLETHREADED queries can only be safely performed if no enqueue or dequeue operations occur while the operation runs. If enqueue or dequeue operations do occur during the execution of a SINGLETHREADED query, it is theoretically possible for the query to enter an infinite loop. Do not do this.
The LFDS700_QUEUE_BSS_QUERY_GET_POTENTIALLY_INACCURATE_COUNT query is not guaranteed to be accurate. Where enqueue and dequeue operations are not guaranteed to be visible by the time the function calls return, similarly, it may be that a count will during its operation not see an element which has been enqueued, or see that an element has been dequeued. In general however it should be bang on; it's just it's not guaranteed.
Example
Coming soon. No, really! (Written 29th Dec 2015).