Annotation of src/external/mit/libuv/dist/docs/src/threading.rst, Revision 1.1
1.1 ! christos 1:
! 2: .. _threading:
! 3:
! 4: Threading and synchronization utilities
! 5: =======================================
! 6:
! 7: libuv provides cross-platform implementations for multiple threading and
! 8: synchronization primitives. The API largely follows the pthreads API.
! 9:
! 10:
! 11: Data types
! 12: ----------
! 13:
! 14: .. c:type:: uv_thread_t
! 15:
! 16: Thread data type.
! 17:
! 18: .. c:type:: void (*uv_thread_cb)(void* arg)
! 19:
! 20: Callback that is invoked to initialize thread execution. `arg` is the same
! 21: value that was passed to :c:func:`uv_thread_create`.
! 22:
! 23: .. c:type:: uv_key_t
! 24:
! 25: Thread-local key data type.
! 26:
! 27: .. c:type:: uv_once_t
! 28:
! 29: Once-only initializer data type.
! 30:
! 31: .. c:type:: uv_mutex_t
! 32:
! 33: Mutex data type.
! 34:
! 35: .. c:type:: uv_rwlock_t
! 36:
! 37: Read-write lock data type.
! 38:
! 39: .. c:type:: uv_sem_t
! 40:
! 41: Semaphore data type.
! 42:
! 43: .. c:type:: uv_cond_t
! 44:
! 45: Condition data type.
! 46:
! 47: .. c:type:: uv_barrier_t
! 48:
! 49: Barrier data type.
! 50:
! 51:
! 52: API
! 53: ---
! 54:
! 55: Threads
! 56: ^^^^^^^
! 57:
! 58: .. c:type:: uv_thread_options_t
! 59:
! 60: Options for spawning a new thread (passed to :c:func:`uv_thread_create_ex`).
! 61:
! 62: ::
! 63:
! 64: typedef struct uv_thread_options_s {
! 65: enum {
! 66: UV_THREAD_NO_FLAGS = 0x00,
! 67: UV_THREAD_HAS_STACK_SIZE = 0x01
! 68: } flags;
! 69: size_t stack_size;
! 70: } uv_thread_options_t;
! 71:
! 72: More fields may be added to this struct at any time, so its exact
! 73: layout and size should not be relied upon.
! 74:
! 75: .. versionadded:: 1.26.0
! 76:
! 77: .. c:function:: int uv_thread_create(uv_thread_t* tid, uv_thread_cb entry, void* arg)
! 78:
! 79: .. versionchanged:: 1.4.1 returns a UV_E* error code on failure
! 80:
! 81: .. c:function:: int uv_thread_create_ex(uv_thread_t* tid, const uv_thread_options_t* params, uv_thread_cb entry, void* arg)
! 82:
! 83: Like :c:func:`uv_thread_create`, but additionally specifies options for creating a new thread.
! 84:
! 85: If `UV_THREAD_HAS_STACK_SIZE` is set, `stack_size` specifies a stack size for the new thread.
! 86: `0` indicates that the default value should be used, i.e. behaves as if the flag was not set.
! 87: Other values will be rounded up to the nearest page boundary.
! 88:
! 89: .. versionadded:: 1.26.0
! 90:
! 91: .. c:function:: uv_thread_t uv_thread_self(void)
! 92: .. c:function:: int uv_thread_join(uv_thread_t *tid)
! 93: .. c:function:: int uv_thread_equal(const uv_thread_t* t1, const uv_thread_t* t2)
! 94:
! 95: Thread-local storage
! 96: ^^^^^^^^^^^^^^^^^^^^
! 97:
! 98: .. note::
! 99: The total thread-local storage size may be limited. That is, it may not be possible to
! 100: create many TLS keys.
! 101:
! 102: .. c:function:: int uv_key_create(uv_key_t* key)
! 103: .. c:function:: void uv_key_delete(uv_key_t* key)
! 104: .. c:function:: void* uv_key_get(uv_key_t* key)
! 105: .. c:function:: void uv_key_set(uv_key_t* key, void* value)
! 106:
! 107: Once-only initialization
! 108: ^^^^^^^^^^^^^^^^^^^^^^^^
! 109:
! 110: Runs a function once and only once. Concurrent calls to :c:func:`uv_once` with the
! 111: same guard will block all callers except one (it's unspecified which one).
! 112: The guard should be initialized statically with the UV_ONCE_INIT macro.
! 113:
! 114: .. c:function:: void uv_once(uv_once_t* guard, void (*callback)(void))
! 115:
! 116: Mutex locks
! 117: ^^^^^^^^^^^
! 118:
! 119: Functions return 0 on success or an error code < 0 (unless the
! 120: return type is void, of course).
! 121:
! 122: .. c:function:: int uv_mutex_init(uv_mutex_t* handle)
! 123: .. c:function:: int uv_mutex_init_recursive(uv_mutex_t* handle)
! 124: .. c:function:: void uv_mutex_destroy(uv_mutex_t* handle)
! 125: .. c:function:: void uv_mutex_lock(uv_mutex_t* handle)
! 126: .. c:function:: int uv_mutex_trylock(uv_mutex_t* handle)
! 127: .. c:function:: void uv_mutex_unlock(uv_mutex_t* handle)
! 128:
! 129: Read-write locks
! 130: ^^^^^^^^^^^^^^^^
! 131:
! 132: Functions return 0 on success or an error code < 0 (unless the
! 133: return type is void, of course).
! 134:
! 135: .. c:function:: int uv_rwlock_init(uv_rwlock_t* rwlock)
! 136: .. c:function:: void uv_rwlock_destroy(uv_rwlock_t* rwlock)
! 137: .. c:function:: void uv_rwlock_rdlock(uv_rwlock_t* rwlock)
! 138: .. c:function:: int uv_rwlock_tryrdlock(uv_rwlock_t* rwlock)
! 139: .. c:function:: void uv_rwlock_rdunlock(uv_rwlock_t* rwlock)
! 140: .. c:function:: void uv_rwlock_wrlock(uv_rwlock_t* rwlock)
! 141: .. c:function:: int uv_rwlock_trywrlock(uv_rwlock_t* rwlock)
! 142: .. c:function:: void uv_rwlock_wrunlock(uv_rwlock_t* rwlock)
! 143:
! 144: Semaphores
! 145: ^^^^^^^^^^
! 146:
! 147: Functions return 0 on success or an error code < 0 (unless the
! 148: return type is void, of course).
! 149:
! 150: .. c:function:: int uv_sem_init(uv_sem_t* sem, unsigned int value)
! 151: .. c:function:: void uv_sem_destroy(uv_sem_t* sem)
! 152: .. c:function:: void uv_sem_post(uv_sem_t* sem)
! 153: .. c:function:: void uv_sem_wait(uv_sem_t* sem)
! 154: .. c:function:: int uv_sem_trywait(uv_sem_t* sem)
! 155:
! 156: Conditions
! 157: ^^^^^^^^^^
! 158:
! 159: Functions return 0 on success or an error code < 0 (unless the
! 160: return type is void, of course).
! 161:
! 162: .. note::
! 163: 1. Callers should be prepared to deal with spurious wakeups on :c:func:`uv_cond_wait`
! 164: and :c:func:`uv_cond_timedwait`.
! 165: 2. The timeout parameter for :c:func:`uv_cond_timedwait` is relative to the time
! 166: at which function is called.
! 167: 3. On z/OS, the timeout parameter for :c:func:`uv_cond_timedwait` is converted to an
! 168: absolute system time at which the wait expires. If the current system clock time
! 169: passes the absolute time calculated before the condition is signaled, an ETIMEDOUT
! 170: error results. After the wait begins, the wait time is not affected by changes
! 171: to the system clock.
! 172:
! 173: .. c:function:: int uv_cond_init(uv_cond_t* cond)
! 174: .. c:function:: void uv_cond_destroy(uv_cond_t* cond)
! 175: .. c:function:: void uv_cond_signal(uv_cond_t* cond)
! 176: .. c:function:: void uv_cond_broadcast(uv_cond_t* cond)
! 177: .. c:function:: void uv_cond_wait(uv_cond_t* cond, uv_mutex_t* mutex)
! 178: .. c:function:: int uv_cond_timedwait(uv_cond_t* cond, uv_mutex_t* mutex, uint64_t timeout)
! 179:
! 180: Barriers
! 181: ^^^^^^^^
! 182:
! 183: Functions return 0 on success or an error code < 0 (unless the
! 184: return type is void, of course).
! 185:
! 186: .. note::
! 187: :c:func:`uv_barrier_wait` returns a value > 0 to an arbitrarily chosen "serializer" thread
! 188: to facilitate cleanup, i.e.
! 189:
! 190: ::
! 191:
! 192: if (uv_barrier_wait(&barrier) > 0)
! 193: uv_barrier_destroy(&barrier);
! 194:
! 195: .. c:function:: int uv_barrier_init(uv_barrier_t* barrier, unsigned int count)
! 196: .. c:function:: void uv_barrier_destroy(uv_barrier_t* barrier)
! 197: .. c:function:: int uv_barrier_wait(uv_barrier_t* barrier)
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to threading.rst CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / external / mit / libuv / dist / docs / src