xSemaphoreTakeRecursive

[Semaphores]

semphr. h

xSemaphoreTakeRecursive( xSemaphoreHandle xMutex, portTickType xBlockTime )

　再帰的 mutex 型セマフォを得る、あるいは「take」するマクロ。
　mutex はそれ以前に xSemaphoreCreateRecursiveMutex () で作成されたものです；
　このマクロが利用可能であるように FreeRTOSConfig.h でconfigUSE_RECURSIVE_MUTEXES を１にセットしなくてはなりません。
このマクロは xSemaphoreCreateMutex () を使って作られた mutexes 上で使うことは出来ません。再帰的mutex は所有者によって繰り返して「taken」することができます。 所有者が xSemaphoreGiveRecursive () を成功した「take」リクエスト分コールするまでmutex は再び利用可能になりません。 例えば、もしタスクが成功裏に同じ mutex を５回「takes」した時、同じく正確に５回 mutex を「given」するまで、 mutex は他のいかなるタスクも利用可能にはならない。

パラメータ：
xMutex
得られている mutex へのハンドル。 これは xSemaphoreCreateRecursiveMutex () によって返されるハンドルです。

xBlockTime
セマフォが利用可能になるのを待つチック時間。 マクロ portTICK_RATE_MS はこれをリアルタイムに変換するために使うことができます。 「ゼロ」のブロックタイムはセマフォをポールするために使うことができます。 もしタスクがすでにセマフォを所有するなら、 xSemaphoreTakeRecursive () は、xBlockTimeの値によらず、直ちリターンする。

リターン：
pdTRUE 　 もしセマフォが得られたなら。
pdFALSE 　もし、セマフォが利用可能でなく、 xBlockTime の期限が切れた。

使用例：

 xSemaphoreHandle xMutex = NULL;

 // A task that creates a mutex.
 void vATask( void * pvParameters )
 {
    // Create the mutex to guard a shared resource.
    xMutex = xSemaphoreCreateRecursiveMutex();
 }

 // A task that uses the mutex.
 void vAnotherTask( void * pvParameters )
 {
    // ... Do other things.

    if( xMutex != NULL )
    {
        // See if we can obtain the mutex.  If the mutex is not available
        // wait 10 ticks to see if it becomes free.    
        if( xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 ) == pdTRUE )
        {
            // We were able to obtain the mutex and can now access the
            // shared resource.

            // ...
            // For some reason due to the nature of the code further calls to 
            // xSemaphoreTakeRecursive() are made on the same mutex.  In real
            // code these would not be just sequential calls as this would make
            // no sense.  Instead the calls are likely to be buried inside
            // a more complex call structure.
            xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 );
            xSemaphoreTakeRecursive( xMutex, ( portTickType ) 10 );

            // The mutex has now been 'taken' three times, so will not be 
            // available to another task until it has also been given back
            // three times.  Again it is unlikely that real code would have
            // these calls sequentially, but instead buried in a more complex
            // call structure.  This is just for illustrative purposes.
            xSemaphoreGiveRecursive( xMutex );
            xSemaphoreGiveRecursive( xMutex );
            xSemaphoreGiveRecursive( xMutex );

            // Now the mutex can be taken by other tasks.
        }
        else
        {
            // We could not obtain the mutex and can therefore not access
            // the shared resource safely.
        }
    }
 }