mirror of
https://github.com/espressif/esp-idf
synced 2025-03-10 01:29:21 -04:00
docs: Provide Chinese translation for api-reference/system/pthread.rst
This commit is contained in:
renpeiying
parent
54f0517724
commit
2dd0d9f330
@ -1,16 +1,18 @@
|
||||
POSIX Threads Support
|
||||
=====================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
ESP-IDF is based on FreeRTOS but offers a range of POSIX-compatible APIs that allow easy porting of third party code. This includes support for common parts of the POSIX Threads "pthreads" API.
|
||||
ESP-IDF is based on FreeRTOS but offers a range of POSIX-compatible APIs that allow easy porting of third-party code. This includes support for common parts of the POSIX Threads ``pthread`` API.
|
||||
|
||||
POSIX Threads are implemented in ESP-IDF as wrappers around equivalent FreeRTOS features. The runtime memory or performance overhead of using the pthreads API is quite low, but not every feature available in either pthreads or FreeRTOS is available via the ESP-IDF pthreads support.
|
||||
|
||||
Pthreads can be used in ESP-IDF by including standard ``pthread.h`` header, which is included in the toolchain libc. An additional ESP-IDF specific header, ``esp_pthread.h``, provides additional non-POSIX APIs for using some ESP-IDF features with pthreads.
|
||||
|
||||
C++ Standard Library implementations for ``std::thread``, ``std::mutex``, ``std::condition_variable``, etc. are implemented using pthreads (via GCC libstdc++). Therefore, restrictions mentioned here also apply to the equivalent C++ standard library functionality.
|
||||
C++ Standard Library implementations for ``std::thread``, ``std::mutex``, ``std::condition_variable``, etc., are realized using pthreads (via GCC libstdc++). Therefore, restrictions mentioned here also apply to the equivalent C++ standard library functionality.
|
||||
|
||||
RTOS Integration
|
||||
----------------
|
||||
@ -19,7 +21,7 @@ Unlike many operating systems using POSIX Threads, ESP-IDF is a real-time operat
|
||||
|
||||
.. note::
|
||||
|
||||
If calling a standard libc or C++ sleep function, such as ``usleep`` defined in ``unistd.h``, then the task will only block and yield the CPU if the sleep time is longer than :ref:`one FreeRTOS tick period <CONFIG_FREERTOS_HZ>`. If the time is shorter, the thread will busy-wait instead of yielding to another RTOS task.
|
||||
When calling a standard libc or C++ sleep function, such as ``usleep`` defined in ``unistd.h``, the task will only block and yield the core if the sleep time is longer than :ref:`one FreeRTOS tick period <CONFIG_FREERTOS_HZ>`. If the time is shorter, the thread will busy-wait instead of yielding to another RTOS task.
|
||||
|
||||
By default, all POSIX Threads have the same RTOS priority, but it is possible to change this by calling a :ref:`custom API <esp-pthread>`.
|
||||
|
||||
@ -28,7 +30,7 @@ Standard Features
|
||||
|
||||
The following standard APIs are implemented in ESP-IDF.
|
||||
|
||||
Refer to standard POSIX Threads documentation, or pthread.h, for details about the standard arguments and behaviour of each function. Differences or limitations compared to the standard APIs are noted below.
|
||||
Refer to `standard POSIX Threads documentation <https://man7.org/linux/man-pages/man7/pthreads.7.html>`__, or ``pthread.h``, for details about the standard arguments and behaviour of each function. Differences or limitations compared to the standard APIs are noted below.
|
||||
|
||||
.. _posix_thread_api:
|
||||
|
||||
@ -36,14 +38,14 @@ Thread APIs
|
||||
^^^^^^^^^^^
|
||||
|
||||
* ``pthread_create()``
|
||||
- The ``attr`` argument is supported for setting stack size and detach state only. Other attribute fields are ignored.
|
||||
- Unlike FreeRTOS task functions, the ``start_routine`` function is allowed to return. A "detached" type thread is automatically deleted if the function returns. The default "joinable" type thread will be suspended until pthread_join() is called on it.
|
||||
- The ``attr`` argument is supported for setting stack size and detach state only. Other attribute fields are ignored.
|
||||
- Unlike FreeRTOS task functions, the ``start_routine`` function is allowed to return. A detached type thread is automatically deleted if the function returns. The default joinable type thread will be suspended until ``pthread_join()`` is called on it.
|
||||
* ``pthread_join()``
|
||||
* ``pthread_detach()``
|
||||
* ``pthread_exit()``
|
||||
* ``sched_yield()``
|
||||
* ``pthread_self()``
|
||||
- An assert will fail if this function is called from a FreeRTOS task which is not a pthread.
|
||||
- An assert will fail if this function is called from a FreeRTOS task which is not a pthread.
|
||||
* ``pthread_equal()``
|
||||
|
||||
Thread Attributes
|
||||
@ -51,7 +53,7 @@ Thread Attributes
|
||||
|
||||
* ``pthread_attr_init()``
|
||||
* ``pthread_attr_destroy()``
|
||||
- This function does not need to free any resources and instead resets the ``attr`` structure to defaults (implementation is same as ``pthread_attr_init()``).
|
||||
- This function does not need to free any resources and instead resets the ``attr`` structure to defaults. The implementation is the same as ``pthread_attr_init()``.
|
||||
* ``pthread_attr_getstacksize()`` / ``pthread_attr_setstacksize()``
|
||||
* ``pthread_attr_getdetachstate()`` / ``pthread_attr_setdetachstate()``
|
||||
|
||||
@ -62,14 +64,14 @@ Once
|
||||
|
||||
Static initializer constant ``PTHREAD_ONCE_INIT`` is supported.
|
||||
|
||||
.. note::
|
||||
|
||||
This function can be called from tasks created using either pthread or FreeRTOS APIs
|
||||
.. note::
|
||||
|
||||
This function can be called from tasks created using either pthread or FreeRTOS APIs.
|
||||
|
||||
Mutexes
|
||||
^^^^^^^
|
||||
|
||||
POSIX Mutexes are implemented as FreeRTOS Mutex Semaphores (normal type for "fast" or "error check" mutexes, and Recursive type for "recursive" mutexes). This means that they have the same priority inheritance behaviour as mutexes created with :cpp:func:`xSemaphoreCreateMutex`.
|
||||
POSIX Mutexes are implemented as FreeRTOS Mutex Semaphores (normal type for "fast" or "error check" mutexes, and Recursive type for "recursive" mutexes). This means that they have the same priority inheritance behavior as mutexes created with :cpp:func:`xSemaphoreCreateMutex`.
|
||||
|
||||
* ``pthread_mutex_init()``
|
||||
* ``pthread_mutex_destroy()``
|
||||
@ -83,15 +85,15 @@ POSIX Mutexes are implemented as FreeRTOS Mutex Semaphores (normal type for "fas
|
||||
|
||||
Static initializer constant ``PTHREAD_MUTEX_INITIALIZER`` is supported, but the non-standard static initializer constants for other mutex types are not supported.
|
||||
|
||||
.. note::
|
||||
|
||||
These functions can be called from tasks created using either pthread or FreeRTOS APIs
|
||||
.. note::
|
||||
|
||||
These functions can be called from tasks created using either pthread or FreeRTOS APIs.
|
||||
|
||||
Condition Variables
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* ``pthread_cond_init()``
|
||||
- The ``attr`` argument is not implemented and is ignored.
|
||||
- The ``attr`` argument is not implemented and is ignored.
|
||||
* ``pthread_cond_destroy()``
|
||||
* ``pthread_cond_signal()``
|
||||
* ``pthread_cond_broadcast()``
|
||||
@ -102,9 +104,9 @@ Static initializer constant ``PTHREAD_COND_INITIALIZER`` is supported.
|
||||
|
||||
* The resolution of ``pthread_cond_timedwait()`` timeouts is the RTOS tick period (see :ref:`CONFIG_FREERTOS_HZ`). Timeouts may be delayed up to one tick period after the requested timeout.
|
||||
|
||||
.. note::
|
||||
|
||||
These functions can be called from tasks created using either pthread or FreeRTOS APIs
|
||||
.. note::
|
||||
|
||||
These functions can be called from tasks created using either pthread or FreeRTOS APIs.
|
||||
|
||||
Semaphores
|
||||
^^^^^^^^^^
|
||||
@ -114,19 +116,19 @@ In ESP-IDF, POSIX **unnamed** semaphores are implemented. The accessible API is
|
||||
* `sem_init() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_init.html>`_
|
||||
* `sem_destroy() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_destroy.html>`_
|
||||
|
||||
- ``pshared`` is ignored. Semaphores can always be shared between FreeRTOS tasks.
|
||||
- ``pshared`` is ignored. Semaphores can always be shared between FreeRTOS tasks.
|
||||
|
||||
* `sem_post() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_post.html>`_
|
||||
|
||||
- If the semaphore has a value of ``SEM_VALUE_MAX`` already, ``-1`` is returned and ``errno`` is set to ``EAGAIN``.
|
||||
- If the semaphore has a value of ``SEM_VALUE_MAX`` already, ``-1`` is returned and ``errno`` is set to ``EAGAIN``.
|
||||
|
||||
* `sem_wait() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_wait.html>`_
|
||||
* `sem_trywait() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_trywait.html>`_
|
||||
* `sem_timedwait() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_timedwait.html>`_
|
||||
|
||||
- The time value passed by abstime will be rounded up to the next FreeRTOS tick.
|
||||
- The actual timeout happens after the tick the time was rounded to and before the following tick.
|
||||
- It is possible, though unlikely, that the task is preempted directly after the timeout calculation, delaying the timeout of the following blocking operating system call by the duration of the preemption.
|
||||
- The time value passed by abstime will be rounded up to the next FreeRTOS tick.
|
||||
- The actual timeout happens after the tick that the time was rounded to and before the following tick.
|
||||
- It is possible, though unlikely, that the task is preempted directly after the timeout calculation, delaying the timeout of the following blocking operating system call by the duration of the preemption.
|
||||
|
||||
* `sem_getvalue() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_getvalue.html>`_
|
||||
|
||||
@ -136,7 +138,7 @@ The following API functions of the POSIX reader-writer locks specification are i
|
||||
|
||||
* `pthread_rwlock_init() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_rwlock_init.html>`_
|
||||
|
||||
- The ``attr`` argument is not implemented and is ignored.
|
||||
- The ``attr`` argument is not implemented and is ignored.
|
||||
|
||||
* `pthread_rwlock_destroy() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_rwlock_destroy.html>`_
|
||||
* `pthread_rwlock_rdlock() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_rwlock_rdlock.html>`_
|
||||
@ -147,23 +149,25 @@ The following API functions of the POSIX reader-writer locks specification are i
|
||||
|
||||
The static initializer constant ``PTHREAD_RWLOCK_INITIALIZER`` is supported.
|
||||
|
||||
.. note:: These functions can be called from tasks created using either pthread or FreeRTOS APIs.
|
||||
.. note::
|
||||
|
||||
These functions can be called from tasks created using either pthread or FreeRTOS APIs.
|
||||
|
||||
Thread-Specific Data
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* ``pthread_key_create()``
|
||||
- The ``destr_function`` argument is supported and will be called if a thread function exits normally, calls ``pthread_exit()``, or if the underlying task is deleted directly using the FreeRTOS function :cpp:func:`vTaskDelete`.
|
||||
- The ``destr_function`` argument is supported and will be called if a thread function exits normally, calls ``pthread_exit()``, or if the underlying task is deleted directly using the FreeRTOS function :cpp:func:`vTaskDelete`.
|
||||
* ``pthread_key_delete()``
|
||||
* ``pthread_setspecific()`` / ``pthread_getspecific()``
|
||||
|
||||
.. note::
|
||||
|
||||
These functions can be called from tasks created using either pthread or FreeRTOS APIs. When calling these functions from tasks created using FreeRTOS APIs, :ref:`CONFIG_FREERTOS_TLSP_DELETION_CALLBACKS` config option must be enabled to ensure the thread-specific data is cleaned up before the task is deleted.
|
||||
.. note::
|
||||
|
||||
.. note::
|
||||
|
||||
There are other options for thread local storage in ESP-IDF, including options with higher performance. See :doc:`/api-guides/thread-local-storage`.
|
||||
These functions can be called from tasks created using either pthread or FreeRTOS APIs. When calling these functions from tasks created using FreeRTOS APIs, :ref:`CONFIG_FREERTOS_TLSP_DELETION_CALLBACKS` config option must be enabled to ensure the thread-specific data is cleaned up before the task is deleted.
|
||||
|
||||
.. note::
|
||||
|
||||
There are other options for thread local storage in ESP-IDF, including options with higher performance. See :doc:`/api-guides/thread-local-storage`.
|
||||
|
||||
Not Implemented
|
||||
---------------
|
||||
@ -173,7 +177,7 @@ The ``pthread.h`` header is a standard header and includes additional APIs and f
|
||||
* ``pthread_cancel()`` returns ``ENOSYS`` if called.
|
||||
* ``pthread_condattr_init()`` returns ``ENOSYS`` if called.
|
||||
|
||||
Other POSIX Threads functions (not listed here) are not implemented and will produce either a compiler or a linker error if referenced from an ESP-IDF application. If you identify a useful API that you would like to see implemented in ESP-IDF, please open a `feature request on GitHub <https://github.com/espressif/esp-idf/issues>` with the details.
|
||||
Other POSIX Threads functions (not listed here) are not implemented and will produce either a compiler or a linker error if referenced from an ESP-IDF application. If you identify a useful API that you would like to see implemented in ESP-IDF, please open a `feature request on GitHub <https://github.com/espressif/esp-idf/issues>`_ with the details.
|
||||
|
||||
.. _esp-pthread:
|
||||
|
||||
@ -183,18 +187,18 @@ ESP-IDF Extensions
|
||||
The API :cpp:func:`esp_pthread_set_cfg` defined in the ``esp_pthreads.h`` header offers custom extensions to control how subsequent calls to ``pthread_create()`` behaves. Currently, the following configuration can be set:
|
||||
|
||||
.. list::
|
||||
- Default stack size of new threads, if not specified when calling ``pthread_create()`` (overrides :ref:`CONFIG_PTHREAD_TASK_STACK_SIZE_DEFAULT`).
|
||||
- RTOS priority of new threads (overrides :ref:`CONFIG_PTHREAD_TASK_PRIO_DEFAULT`).
|
||||
:not CONFIG_FREERTOS_UNICORE: - Core affinity / core pinning of new threads (overrides :ref:`CONFIG_PTHREAD_TASK_CORE_DEFAULT`).
|
||||
- FreeRTOS task name for new threads (overrides :ref:`CONFIG_PTHREAD_TASK_NAME_DEFAULT`)
|
||||
- Default stack size of new threads, if not specified when calling ``pthread_create()`` (overrides :ref:`CONFIG_PTHREAD_TASK_STACK_SIZE_DEFAULT`).
|
||||
- RTOS priority of new threads (overrides :ref:`CONFIG_PTHREAD_TASK_PRIO_DEFAULT`).
|
||||
:not CONFIG_FREERTOS_UNICORE: - Core affinity / core pinning of new threads (overrides :ref:`CONFIG_PTHREAD_TASK_CORE_DEFAULT`).
|
||||
- FreeRTOS task name for new threads (overrides :ref:`CONFIG_PTHREAD_TASK_NAME_DEFAULT`)
|
||||
|
||||
This configuration is scoped to the calling thread (or FreeRTOS task), meaning that :cpp:func:`esp_pthread_set_cfg` can be called independently in different threads or tasks. If the ``inherit_cfg`` flag is set in the current configuration then any new thread created will inherit the creator's configuration (if that thread calls ``pthread_create()`` recursively), otherwise the new thread will have the default configuration.
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
- :example:`system/pthread` demonstrates using the pthreads API to create threads
|
||||
- :example:`cxx/pthread` demonstrates using C++ Standard Library functions with threads
|
||||
- :example:`system/pthread` demonstrates using the pthreads API to create threads.
|
||||
- :example:`cxx/pthread` demonstrates using C++ Standard Library functions with threads.
|
||||
|
||||
|
||||
API Reference
|
||||
|
||||
@ -1 +1,207 @@
|
||||
.. include:: ../../../en/api-reference/system/pthread.rst
|
||||
POSIX Thread
|
||||
============
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
概述
|
||||
--------
|
||||
|
||||
ESP-IDF 基于 FreeRTOS，但提供了一系列与 POSIX 兼容的 API，以便轻松移植第三方代码，例如支持 pthread 常用的 ``pthread`` API。
|
||||
|
||||
在 ESP-IDF 中，pthread 对 FreeRTOS 中的等效功能进行了包装。pthread API 所需的运行内存或性能开销很低，但 pthread 或 FreeRTOS 的可用功能并非都可以通过 ESP-IDF 的 pthread 支持来实现。
|
||||
|
||||
添加标准 ``pthread.h`` 头文件后可以在 ESP-IDF 中使用 pthread，该头文件已包含在工具链 libc 中。还有另一个专用于 ESP-IDF 的头文件 ``esp_pthread.h``，其中提供了一些额外的非 POSIX API，以便通过 pthread 使用一些 ESP-IDF 功能。
|
||||
|
||||
C++ 标准库中的 ``std::thread``、``std::mutex``、``std::condition_variable`` 等功能也是通过 pthread（利用 GCC libstdc++）实现的。因此，本文档提到的限制条件也同样适用于 C++ 标准库中等效功能。
|
||||
|
||||
RTOS 集成
|
||||
----------------
|
||||
|
||||
与许多使用 pthread 的操作系统不同，ESP-IDF 是一个实时操作系统，具有实时调度程序。这意味着只有当一个更高优先级的任务准备就绪、线程在 OS 同步结构（如 mutex）上发生阻塞、或者线程调用 ``sleep``、:cpp:func:`vTaskDelay`、``usleep`` 等函数时，线程才会停止运行。
|
||||
|
||||
.. note::
|
||||
|
||||
如果调用 C 标准库或 C++ sleep 函数，例如在 ``unistd.h`` 中定义的 ``usleep``，那么只有当睡眠时间超过 :ref:`一个 FreeRTOS 滴答周期 <CONFIG_FREERTOS_HZ>` 时，任务才会阻塞并让出内核。如果时间较短，线程将处于忙等待状态，不会让步给另一个 RTOS 任务。
|
||||
|
||||
默认情况下，所有 pthread 具有相同的 RTOS 优先级，但可以通过调用 :ref:`ESP-IDF 提供的扩展 API <esp-pthread>` 对此优先级进行更改。
|
||||
|
||||
标准功能
|
||||
-----------------
|
||||
|
||||
ESP-IDF 中实现了以下标准 API。
|
||||
|
||||
请参考 `标准 pthread 文档 <https://man7.org/linux/man-pages/man7/pthreads.7.html>`__ 或 ``pthread.h``，了解每个函数标准参数和行为的详细信息。下文还列出了 pthread API 与标准 API 相比的差异或局限性。
|
||||
|
||||
.. _posix_thread_api:
|
||||
|
||||
线程 API
|
||||
^^^^^^^^^^^
|
||||
|
||||
* ``pthread_create()``
|
||||
- ``attr`` 参数仅支持设置堆栈大小和分离状态，其他属性字段将被忽略。
|
||||
- 与 FreeRTOS 任务函数不同，``start_routine`` 函数允许返回。如果函数返回，分离类型的线程会被自动删除。而默认的可连接类型线程将被挂起，直到调用 ``pthread_join()``。
|
||||
* ``pthread_join()``
|
||||
* ``pthread_detach()``
|
||||
* ``pthread_exit()``
|
||||
* ``sched_yield()``
|
||||
* ``pthread_self()``
|
||||
- 如果从不是 pthread 的 FreeRTOS 任务中调用此函数，断言会失败。
|
||||
* ``pthread_equal()``
|
||||
|
||||
线程属性
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
* ``pthread_attr_init()``
|
||||
* ``pthread_attr_destroy()``
|
||||
- 此函数不需要释放任何资源，而是将 ``attr`` 结构体重置为默认值。其实现与 ``pthread_attr_init()`` 相同。
|
||||
* ``pthread_attr_getstacksize()`` / ``pthread_attr_setstacksize()``
|
||||
* ``pthread_attr_getdetachstate()`` / ``pthread_attr_setdetachstate()``
|
||||
|
||||
Once
|
||||
^^^^^^^^
|
||||
|
||||
* ``pthread_once()``
|
||||
|
||||
支持静态初始化常量 ``PTHREAD_ONCE_INIT``。
|
||||
|
||||
.. note::
|
||||
|
||||
在使用 pthread 或 FreeRTOS API 创建的任务中都可以调用此函数。
|
||||
|
||||
互斥锁
|
||||
^^^^^^^
|
||||
|
||||
POSIX 互斥锁被实现为 FreeRTOS 互斥信号量（普通类型用于“快速”或“错误检查”互斥锁，递归类型用于“递归”互斥锁），因此与使用 :cpp:func:`xSemaphoreCreateMutex` 创建的互斥锁具有相同的优先级继承行为。
|
||||
|
||||
* ``pthread_mutex_init()``
|
||||
* ``pthread_mutex_destroy()``
|
||||
* ``pthread_mutex_lock()``
|
||||
* ``pthread_mutex_timedlock()``
|
||||
* ``pthread_mutex_trylock()``
|
||||
* ``pthread_mutex_unlock()``
|
||||
* ``pthread_mutexattr_init()``
|
||||
* ``pthread_mutexattr_destroy()``
|
||||
* ``pthread_mutexattr_gettype()`` / ``pthread_mutexattr_settype()``
|
||||
|
||||
支持静态初始化常量 ``PTHREAD_MUTEX_INITIALIZER``，但不支持其他互斥锁类型的非标准静态初始化常量。
|
||||
|
||||
.. note::
|
||||
|
||||
在使用 pthread 或 FreeRTOS API 创建的任务中都可以调用这些函数。
|
||||
|
||||
条件变量
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* ``pthread_cond_init()``
|
||||
- ``attr`` 参数未实现，将被忽略。
|
||||
* ``pthread_cond_destroy()``
|
||||
* ``pthread_cond_signal()``
|
||||
* ``pthread_cond_broadcast()``
|
||||
* ``pthread_cond_wait()``
|
||||
* ``pthread_cond_timedwait()``
|
||||
|
||||
支持静态初始化常量 ``PTHREAD_COND_INITIALIZER``。
|
||||
|
||||
* ``pthread_cond_timedwait()`` 超时的分辨率为 RTOS 滴答周期（参见 :ref:`CONFIG_FREERTOS_HZ`）。在请求超时后，超时最多会延迟一个滴答周期。
|
||||
|
||||
.. note::
|
||||
|
||||
在使用 pthread 或 FreeRTOS API 创建的任务中都可以调用这些函数。
|
||||
|
||||
信号量
|
||||
^^^^^^^^^^
|
||||
|
||||
ESP-IDF 中实现了 POSIX **未命名信号量**，下文介绍了可访问的 API。除非另有说明，否则 ESP-IDF 中未命名信号量的实现遵循 `POSIX 标准规定的信号量 <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/semaphore.h.html>`_。
|
||||
|
||||
* `sem_init() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_init.html>`_
|
||||
* `sem_destroy() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_destroy.html>`_
|
||||
|
||||
- ``pshared`` 被忽略。信号量始终可以在 FreeRTOS 任务之间共享。
|
||||
|
||||
* `sem_post() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_post.html>`_
|
||||
|
||||
- 如果信号量的值已经是 ``SEM_VALUE_MAX``，则返回 ``-1``，并将 ``errno`` 设置为 ``EAGAIN``。
|
||||
|
||||
* `sem_wait() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_wait.html>`_
|
||||
* `sem_trywait() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_trywait.html>`_
|
||||
* `sem_timedwait() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_timedwait.html>`_
|
||||
|
||||
- 通过 abstime 传递的时间值将被向上舍入到下一个 FreeRTOS 时钟滴答。
|
||||
- 超时实际发生在被舍入到的滴答之后，下一个滴答之前。
|
||||
- 在计算超时后，任务有可能被立即抢占（可能性较小），从而延迟下一个阻塞操作系统调用的超时，延迟的时间等于抢占的持续时间。
|
||||
|
||||
* `sem_getvalue() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_getvalue.html>`_
|
||||
|
||||
读/写锁
|
||||
^^^^^^^^^^^^^^^^
|
||||
ESP-IDF 中实现了 POSIX 读写锁规范的以下 API 函数：
|
||||
|
||||
* `pthread_rwlock_init() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_rwlock_init.html>`_
|
||||
|
||||
- ``attr`` 参数未实现，将被忽略。
|
||||
|
||||
* `pthread_rwlock_destroy() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_rwlock_destroy.html>`_
|
||||
* `pthread_rwlock_rdlock() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_rwlock_rdlock.html>`_
|
||||
* `pthread_rwlock_tryrdlock() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_rwlock_tryrdlock.html>`_
|
||||
* `pthread_rwlock_wrlock() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_rwlock_wrlock.html>`_
|
||||
* `pthread_rwlock_trywrlock() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_rwlock_trywrlock.html>`_
|
||||
* `pthread_rwlock_unlock() <https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_rwlock_unlock.html>`_
|
||||
|
||||
支持静态初始化器常量 ``PTHREAD_RWLOCK_INITIALIZER``。
|
||||
|
||||
.. note::
|
||||
|
||||
在 pthread 或 FreeRTOS API 创建的任务中都可以调用此函数。
|
||||
|
||||
线程特定数据
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* ``pthread_key_create()``
|
||||
- 支持 ``destr_function`` 参数。如果线程函数正常退出并调用 ``pthread_exit()``，此参数就会被调用，或者在使用 FreeRTOS 函数 :cpp:func:`vTaskDelete` 直接删除了底层任务时被调用。
|
||||
* ``pthread_key_delete()``
|
||||
* ``pthread_setspecific()`` / ``pthread_getspecific()``
|
||||
|
||||
.. note::
|
||||
|
||||
在 pthread 或 FreeRTOS API 创建的任务中都可以调用此函数。当从 FreeRTOS API 创建的任务中调用这些函数时，必须先启用 :ref:`CONFIG_FREERTOS_TLSP_DELETION_CALLBACKS` 配置选项，以确保在删除任务之前清理线程数据。
|
||||
|
||||
.. note::
|
||||
|
||||
ESP-IDF 中还有其他的线程本地存储选项，包括性能更高的选项。参见 :doc:`/api-guides/thread-local-storage`。
|
||||
|
||||
未实现 API
|
||||
---------------
|
||||
|
||||
``pthread.h`` 头文件是一个标准头文件，包含了在 ESP-IDF 中未实现的额外 API 和功能，包括：
|
||||
|
||||
* 如果调用 ``pthread_cancel()``，返回 ``ENOSYS``。
|
||||
* ``pthread_condattr_init()`` 如果被调用，返回 ``ENOSYS``。
|
||||
|
||||
其他未列出的 pthread 函数未在 ESP-IDF 中实现，如果从 ESP-IDF 应用程序中直接引用，将产生编译器错误或链接器错误。如果希望 ESP-IDF 支持某个尚未实现的 API，请 `在 GitHub 上发起功能请求 <https://github.com/espressif/esp-idf/issues>`_ 并提供详细信息。
|
||||
|
||||
.. _esp-pthread:
|
||||
|
||||
ESP-IDF 扩展
|
||||
------------------
|
||||
|
||||
在 ``esp_pthreads.h`` 头文件中定义的 API :cpp:func:`esp_pthread_set_cfg` 提供了自定义扩展，能够对后续 ``pthread_create()`` 的调用行为进行控制。目前提供以下配置：
|
||||
|
||||
.. list::
|
||||
- 如果调用 ``pthread_create()`` 时未指定默认堆栈大小，可设置新线程的默认堆栈大小（覆盖 :ref:`CONFIG_PTHREAD_TASK_STACK_SIZE_DEFAULT`）。
|
||||
- 新线程的 RTOS 优先级（覆盖 :ref:`CONFIG_PTHREAD_TASK_PRIO_DEFAULT`）。
|
||||
:not CONFIG_FREERTOS_UNICORE: - 新线程的内核亲和性/内核固定（覆盖 :ref:`CONFIG_PTHREAD_TASK_CORE_DEFAULT`）。
|
||||
- 新线程的 FreeRTOS 任务名称（覆盖 :ref:`CONFIG_PTHREAD_TASK_NAME_DEFAULT`）
|
||||
|
||||
此配置的作用范围是调用线程或 FreeRTOS 任务，这意味着 :cpp:func:`esp_pthread_set_cfg` 可以在不同的线程或任务中独立调用。如果在当前配置中设置了 ``inherit_cfg`` 标志，那么当一个线程递归调用 ``pthread_create()`` 时，任何新创建的线程都会继承该线程的配置，否则新线程将采用默认配置。
|
||||
|
||||
示例
|
||||
--------
|
||||
|
||||
- :example:`system/pthread` 演示了如何使用 pthread API 创建线程。
|
||||
- :example:`cxx/pthread` 演示了如何通过线程使用 C++ 标准库函数。
|
||||
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_pthread.inc
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user