FreeRTOS-Tetris/queue_8h_source.html

/*

    FreeRTOS V9.0.0 - Copyright (C) 2016 Real Time Engineers Ltd.

    All rights reserved


    VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.


    This file is part of the FreeRTOS distribution.


    FreeRTOS is free software; you can redistribute it and/or modify it under

    the terms of the GNU General Public License (version 2) as published by the

    Free Software Foundation >>>> AND MODIFIED BY <<<< the FreeRTOS exception.


    ***************************************************************************

    >>!   NOTE: The modification to the GPL is included to allow you to     !<<

    >>!   distribute a combined work that includes FreeRTOS without being   !<<

    >>!   obliged to provide the source code for proprietary components     !<<

    >>!   outside of the FreeRTOS kernel.                                   !<<

    ***************************************************************************


    FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY

    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS

    FOR A PARTICULAR PURPOSE.  Full license text is available on the following

    link: http://www.freertos.org/a00114.html


    ***************************************************************************

     *                                                                       *

     *    FreeRTOS provides completely free yet professionally developed,    *

     *    robust, strictly quality controlled, supported, and cross          *

     *    platform software that is more than just the market leader, it     *

     *    is the industry's de facto standard.                               *

     *                                                                       *

     *    Help yourself get started quickly while simultaneously helping     *

     *    to support the FreeRTOS project by purchasing a FreeRTOS           *

     *    tutorial book, reference manual, or both:                          *

     *    http://www.FreeRTOS.org/Documentation                              *

     *                                                                       *

    ***************************************************************************


    http://www.FreeRTOS.org/FAQHelp.html - Having a problem?  Start by reading

    the FAQ page "My application does not run, what could be wrong?".  Have you

    defined configASSERT()?


    http://www.FreeRTOS.org/support - In return for receiving this top quality

    embedded software for free we request you assist our global community by

    participating in the support forum.


    http://www.FreeRTOS.org/training - Investing in training allows your team to

    be as productive as possible as early as possible.  Now you can receive

    FreeRTOS training directly from Richard Barry, CEO of Real Time Engineers

    Ltd, and the world's leading authority on the world's leading RTOS.


    http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products,

    including FreeRTOS+Trace - an indispensable productivity tool, a DOS

    compatible FAT file system, and our tiny thread aware UDP/IP stack.


    http://www.FreeRTOS.org/labs - Where new FreeRTOS products go to incubate.

    Come and try FreeRTOS+TCP, our new open source TCP/IP stack for FreeRTOS.


    http://www.OpenRTOS.com - Real Time Engineers ltd. license FreeRTOS to High

    Integrity Systems ltd. to sell under the OpenRTOS brand.  Low cost OpenRTOS

    licenses offer ticketed support, indemnification and commercial middleware.


    http://www.SafeRTOS.com - High Integrity Systems also provide a safety

    engineered and independently SIL3 certified version for use in safety and

    mission critical applications that require provable dependability.


    1 tab == 4 spaces!

*/


// Doxygen Groups ***********************************************************************

#ifndef QUEUE_H

#define QUEUE_H


#ifndef INC_FREERTOS_H

#error "include FreeRTOS.h" must appear in source files before "include queue.h"

#endif


#ifdef __cplusplus

extern "C" {

#endif


// **************************************************************************************

// Queue Handles ************************************************************************

// **************************************************************************************


typedef void *QueueHandle_t;


typedef void *QueueSetHandle_t;


typedef void *QueueSetMemberHandle_t;


/* For internal use only. */

#define queueSEND_TO_BACK       ( ( BaseType_t ) 0 )

#define queueSEND_TO_FRONT      ( ( BaseType_t ) 1 )

#define queueOVERWRITE          ( ( BaseType_t ) 2 )


/* For internal use only.  These definitions *must* match those in queue.c. */

#define queueQUEUE_TYPE_BASE                ( ( uint8_t ) 0U )

#define queueQUEUE_TYPE_SET                 ( ( uint8_t ) 0U )

#define queueQUEUE_TYPE_MUTEX               ( ( uint8_t ) 1U )

#define queueQUEUE_TYPE_COUNTING_SEMAPHORE  ( ( uint8_t ) 2U )

#define queueQUEUE_TYPE_BINARY_SEMAPHORE    ( ( uint8_t ) 3U )

#define queueQUEUE_TYPE_RECURSIVE_MUTEX     ( ( uint8_t ) 4U )


// **************************************************************************************

// Queue Creation ***********************************************************************

// **************************************************************************************


#if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )

#define xQueueCreate( uxQueueLength, uxItemSize ) xQueueGenericCreate( ( uxQueueLength ), ( uxItemSize ), ( queueQUEUE_TYPE_BASE ) )

#endif


#if( configSUPPORT_STATIC_ALLOCATION == 1 )

#define xQueueCreateStatic( uxQueueLength, uxItemSize, pucQueueStorage, pxQueueBuffer ) xQueueGenericCreateStatic( ( uxQueueLength ), ( uxItemSize ), ( pucQueueStorage ), ( pxQueueBuffer ), ( queueQUEUE_TYPE_BASE ) )

#endif /* configSUPPORT_STATIC_ALLOCATION */


#if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )

QueueHandle_t xQueueGenericCreate(const UBaseType_t uxQueueLength, const UBaseType_t uxItemSize, const uint8_t ucQueueType) PRIVILEGED_FUNCTION;

#endif


#if( configSUPPORT_STATIC_ALLOCATION == 1 )

QueueHandle_t xQueueGenericCreateStatic(const UBaseType_t uxQueueLength, const UBaseType_t uxItemSize, uint8_t *pucQueueStorage, StaticQueue_t *pxStaticQueue, const uint8_t ucQueueType) PRIVILEGED_FUNCTION;

#endif


// **************************************************************************************

// Queue Deletion ***********************************************************************

// **************************************************************************************

void vQueueDelete(QueueHandle_t xQueue) PRIVILEGED_FUNCTION;


// **************************************************************************************

// xQueueSend ***************************************************************************

// **************************************************************************************

#define xQueueSend( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_BACK )


#define xQueueSendToFront( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_FRONT )


#define xQueueSendToBack( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_BACK )


BaseType_t xQueueGenericSend(QueueHandle_t xQueue, const void *const pvItemToQueue, TickType_t xTicksToWait, const BaseType_t xCopyPosition) PRIVILEGED_FUNCTION;


#define xQueueOverwrite( xQueue, pvItemToQueue ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), 0, queueOVERWRITE )


// **************************************************************************************

// Queue Sending from ISR ***************************************************************

// **************************************************************************************


#define xQueueSendToFrontFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_FRONT )


#define xQueueSendToBackFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK )


#define xQueueOverwriteFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueOVERWRITE )


#define xQueueSendFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK )


BaseType_t xQueueGenericSendFromISR(QueueHandle_t xQueue, const void *const pvItemToQueue, BaseType_t *const pxHigherPriorityTaskWoken, const BaseType_t xCopyPosition) PRIVILEGED_FUNCTION;


//***************************************************************************************

// Queue Receiving **********************************************************************

//***************************************************************************************


#define xQueuePeek( xQueue, pvBuffer, xTicksToWait ) xQueueGenericReceive( ( xQueue ), ( pvBuffer ), ( xTicksToWait ), pdTRUE )


#define xQueueReceive( xQueue, pvBuffer, xTicksToWait ) xQueueGenericReceive( ( xQueue ), ( pvBuffer ), ( xTicksToWait ), pdFALSE )


BaseType_t xQueueGenericReceive(QueueHandle_t xQueue, void *const pvBuffer, TickType_t xTicksToWait, const BaseType_t xJustPeek) PRIVILEGED_FUNCTION;


// **************************************************************************************

// Queue Receiving from ISR *************************************************************

// **************************************************************************************

BaseType_t xQueuePeekFromISR(QueueHandle_t xQueue, void *const pvBuffer) PRIVILEGED_FUNCTION;


BaseType_t xQueueReceiveFromISR(QueueHandle_t xQueue, void *const pvBuffer, BaseType_t *const pxHigherPriorityTaskWoken) PRIVILEGED_FUNCTION;


// **************************************************************************************

// Queue Utility Functions **************************************************************

// **************************************************************************************


UBaseType_t uxQueueMessagesWaiting(const QueueHandle_t xQueue) PRIVILEGED_FUNCTION;


UBaseType_t uxQueueSpacesAvailable(const QueueHandle_t xQueue) PRIVILEGED_FUNCTION;


BaseType_t xQueueIsQueueEmptyFromISR(const QueueHandle_t xQueue) PRIVILEGED_FUNCTION;


BaseType_t xQueueIsQueueFullFromISR(const QueueHandle_t xQueue) PRIVILEGED_FUNCTION;


UBaseType_t uxQueueMessagesWaitingFromISR(const QueueHandle_t xQueue) PRIVILEGED_FUNCTION;


/*

 * Reset a queue back to its original empty state.  The return value is now

 * obsolete and is always set to pdPASS.

 */

#define xQueueReset( xQueue ) xQueueGenericReset( xQueue, pdFALSE )


// **************************************************************************************

// Queue Registration *******************************************************************

// **************************************************************************************

#if( configQUEUE_REGISTRY_SIZE > 0 )

void vQueueAddToRegistry(QueueHandle_t xQueue, const char *pcName) PRIVILEGED_FUNCTION;   /*lint !e971 Unqualified char types are allowed for strings and single characters only. */

#endif


#if( configQUEUE_REGISTRY_SIZE > 0 )

void vQueueUnregisterQueue(QueueHandle_t xQueue) PRIVILEGED_FUNCTION;

#endif


#if( configQUEUE_REGISTRY_SIZE > 0 )

const char *pcQueueGetName(QueueHandle_t xQueue) PRIVILEGED_FUNCTION;   /*lint !e971 Unqualified char types are allowed for strings and single characters only. */

#endif


// **************************************************************************************

// Queue Sets ***************************************************************************

// **************************************************************************************


QueueSetHandle_t xQueueCreateSet(const UBaseType_t uxEventQueueLength) PRIVILEGED_FUNCTION;


BaseType_t xQueueAddToSet(QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t xQueueSet) PRIVILEGED_FUNCTION;


BaseType_t xQueueRemoveFromSet(QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t xQueueSet) PRIVILEGED_FUNCTION;


QueueSetMemberHandle_t xQueueSelectFromSet(QueueSetHandle_t xQueueSet, const TickType_t xTicksToWait) PRIVILEGED_FUNCTION;


QueueSetMemberHandle_t xQueueSelectFromSetFromISR(QueueSetHandle_t xQueueSet) PRIVILEGED_FUNCTION;


// **************************************************************************************

// Other/Undocumented *******************************************************************

// **************************************************************************************


/* Not public API functions. */

void vQueueWaitForMessageRestricted(QueueHandle_t xQueue, TickType_t xTicksToWait, const BaseType_t xWaitIndefinitely) PRIVILEGED_FUNCTION;

BaseType_t xQueueGenericReset(QueueHandle_t xQueue, BaseType_t xNewQueue) PRIVILEGED_FUNCTION;

void vQueueSetQueueNumber(QueueHandle_t xQueue, UBaseType_t uxQueueNumber) PRIVILEGED_FUNCTION;

UBaseType_t uxQueueGetQueueNumber(QueueHandle_t xQueue) PRIVILEGED_FUNCTION;

uint8_t ucQueueGetQueueType(QueueHandle_t xQueue) PRIVILEGED_FUNCTION;


/*

 * The functions defined above are for passing data to and from tasks.  The

 * functions below are the equivalents for passing data to and from

 * co-routines.

 *

 * These functions are called from the co-routine macro implementation and

 * should not be called directly from application code.  Instead use the macro

 * wrappers defined within croutine.h.

 */

BaseType_t xQueueCRSendFromISR(QueueHandle_t xQueue, const void *pvItemToQueue, BaseType_t xCoRoutinePreviouslyWoken);

BaseType_t xQueueCRReceiveFromISR(QueueHandle_t xQueue, void *pvBuffer, BaseType_t *pxTaskWoken);

BaseType_t xQueueCRSend(QueueHandle_t xQueue, const void *pvItemToQueue, TickType_t xTicksToWait);

BaseType_t xQueueCRReceive(QueueHandle_t xQueue, void *pvBuffer, TickType_t xTicksToWait);


/*

 * For internal use only.  Use xSemaphoreCreateMutex(),

 * xSemaphoreCreateCounting() or xSemaphoreGetMutexHolder() instead of calling

 * these functions directly.

 */

QueueHandle_t xQueueCreateMutex(const uint8_t ucQueueType) PRIVILEGED_FUNCTION;

QueueHandle_t xQueueCreateMutexStatic(const uint8_t ucQueueType, StaticQueue_t *pxStaticQueue) PRIVILEGED_FUNCTION;

QueueHandle_t xQueueCreateCountingSemaphore(const UBaseType_t uxMaxCount, const UBaseType_t uxInitialCount) PRIVILEGED_FUNCTION;

QueueHandle_t xQueueCreateCountingSemaphoreStatic(const UBaseType_t uxMaxCount, const UBaseType_t uxInitialCount, StaticQueue_t *pxStaticQueue) PRIVILEGED_FUNCTION;

void *xQueueGetMutexHolder(QueueHandle_t xSemaphore) PRIVILEGED_FUNCTION;


/*

 * For internal use only.  Use xSemaphoreTakeMutexRecursive() or

 * xSemaphoreGiveMutexRecursive() instead of calling these functions directly.

 */

BaseType_t xQueueTakeMutexRecursive(QueueHandle_t xMutex, TickType_t xTicksToWait) PRIVILEGED_FUNCTION;

BaseType_t xQueueGiveMutexRecursive(QueueHandle_t pxMutex) PRIVILEGED_FUNCTION;

BaseType_t xQueueGiveFromISR(QueueHandle_t xQueue, BaseType_t *const pxHigherPriorityTaskWoken) PRIVILEGED_FUNCTION;


#ifdef __cplusplus

}

#endif


#endif /* QUEUE_H */