xSemaphoreCreateCounting
[信号量]

semphr. h

SemaphoreHandle_t xSemaphoreCreateCounting( UBaseType_t uxMaxCount,
                                            UBaseType_t uxInitialCount);

创建计数信号量 并返回句柄，通过该句柄可以引用新创建的信号量。 configSUPPORT_DYNAMIC_ALLOCATION 必须在 FreeRTOSConfig.h 中被设置为 1，或保留未定义状态（此时，它默认 默认为1) ，才能使用此RTOS API 函数。

每个计数信号量需要少量RAM ，用于保持 信号量的状态。 如果使用 xSemaphoreCreateCounting () 创建计数信号量 则会从 堆自动分配所需的。 RAM FreeRTOS 如果使用 xSemaphoreCreateCountingStatic() 创建计数信号量， 则 RAM会由应用程序编写器提供，这需要其他的 但允许在编译时静态分配 RAM 。 请参阅静态分配与 动态分配页面以了解更多信息。

计数信号量通常用于两种情况：

1. 盘点事件。

   在此使用场景中， 每次发生事件（增加信号量计数值）时 ，事件处理程序都会“给出”信号量，处理程序任务 每次处理事件时，都会“获取”信号量 （递减信号量计数值）。 因此，计数值是 已发生的事件数量和 已处理的数量之间的差。 在这种情况下， 初始计数值最好为零。

   请注意， 使用直接到任务通知通常可以更有效地实现相同的功能。

2. 资源管理。

   在此使用方案中，计数值表示可用的资源数量 。 若要获取对资源的控制权，任务就必须首先获取 信号量-递减信号量计数值。 当计数值 达到零，则表示没有可用资源。 当任务结束使用 资源时，它会“返回”信号量-增加信号量计数 值。 在这种情况下，初始计数值最好 等于所述最大计数值，表明所有资源都是可用的。

参数：

uxMaxCount	可以达到的最大计数值。 当信号量达到此值时，它不能再被“给定”。
uxInitialCount	创建信号量时分配给信号量的计数值。

返回：

如果已成功创建信号量，则将返回该信号量的句柄 。 如果因为保留信号量所需的RAM 无法分配而无法创建信号量， 则会返回 NULL。

用法示例：

void vATask( void * pvParameters )
{
SemaphoreHandle_t xSemaphore;

    /* Create a counting semaphore that has a maximum count of 10 and an
    initial count of 0. */
    xSemaphore = xSemaphoreCreateCounting( 10, 0 );

    if( xSemaphore != NULL )
    {
        /* The semaphore was created successfully. */
    }
}