diff options
author | Eli Zaretskii <eliz@gnu.org> | 2016-12-10 11:31:11 +0200 |
---|---|---|
committer | Eli Zaretskii <eliz@gnu.org> | 2016-12-10 11:31:11 +0200 |
commit | c364d62f89a499d22f06f63e81ec7819f51596fa (patch) | |
tree | 00f04506a0e7ed9830127592fb2df46fbd6808b2 | |
parent | e4df093e6058c4338a1ea885d44fd0be7f032b8c (diff) | |
download | emacs-c364d62f89a499d22f06f63e81ec7819f51596fa.tar.gz |
Improve doc strings in thread.c
* src/thread.c (Fmake_condition_variable, Fcondition_wait)
(Fcondition_notify, Fcondition_mutex, Fcondition_name, Fmake_thread)
(Fthread_join, Fall_threads): Doc fixes.
-rw-r--r-- | src/thread.c | 61 |
1 files changed, 31 insertions, 30 deletions
diff --git a/src/thread.c b/src/thread.c index b2f8561f923..ee5b82da905 100644 --- a/src/thread.c +++ b/src/thread.c @@ -301,7 +301,7 @@ finalize_one_mutex (struct Lisp_Mutex *mutex) DEFUN ("make-condition-variable", Fmake_condition_variable, Smake_condition_variable, 1, 2, 0, - doc: /* Make a condition variable. + doc: /* Make a condition variable associated with MUTEX. A condition variable provides a way for a thread to sleep while waiting for a state change. @@ -355,23 +355,23 @@ condition_wait_callback (void *arg) } DEFUN ("condition-wait", Fcondition_wait, Scondition_wait, 1, 1, 0, - doc: /* Wait for the condition variable to be notified. -CONDITION is the condition variable to wait on. + doc: /* Wait for the condition variable COND to be notified. +COND is the condition variable to wait on. -The mutex associated with CONDITION must be held when this is called. +The mutex associated with COND must be held when this is called. It is an error if it is not held. -This releases the mutex and waits for CONDITION to be notified or for +This releases the mutex and waits for COND to be notified or for this thread to be signalled with `thread-signal'. When -`condition-wait' returns, the mutex will again be locked by this -thread. */) - (Lisp_Object condition) +`condition-wait' returns, COND's mutex will again be locked by +this thread. */) + (Lisp_Object cond) { struct Lisp_CondVar *cvar; struct Lisp_Mutex *mutex; - CHECK_CONDVAR (condition); - cvar = XCONDVAR (condition); + CHECK_CONDVAR (cond); + cvar = XCONDVAR (cond); mutex = XMUTEX (cvar->mutex); if (!lisp_mutex_owned_p (&mutex->mutex)) @@ -409,24 +409,24 @@ condition_notify_callback (void *arg) } DEFUN ("condition-notify", Fcondition_notify, Scondition_notify, 1, 2, 0, - doc: /* Notify a condition variable. -This wakes a thread waiting on CONDITION. + doc: /* Notify COND, a condition variable. +This wakes a thread waiting on COND. If ALL is non-nil, all waiting threads are awoken. -The mutex associated with CONDITION must be held when this is called. +The mutex associated with COND must be held when this is called. It is an error if it is not held. -This releases the mutex when notifying CONDITION. When +This releases COND's mutex when notifying COND. When `condition-notify' returns, the mutex will again be locked by this thread. */) - (Lisp_Object condition, Lisp_Object all) + (Lisp_Object cond, Lisp_Object all) { struct Lisp_CondVar *cvar; struct Lisp_Mutex *mutex; struct notify_args args; - CHECK_CONDVAR (condition); - cvar = XCONDVAR (condition); + CHECK_CONDVAR (cond); + cvar = XCONDVAR (cond); mutex = XMUTEX (cvar->mutex); if (!lisp_mutex_owned_p (&mutex->mutex)) @@ -440,26 +440,26 @@ thread. */) } DEFUN ("condition-mutex", Fcondition_mutex, Scondition_mutex, 1, 1, 0, - doc: /* Return the mutex associated with CONDITION. */) - (Lisp_Object condition) + doc: /* Return the mutex associated with condition variable COND. */) + (Lisp_Object cond) { struct Lisp_CondVar *cvar; - CHECK_CONDVAR (condition); - cvar = XCONDVAR (condition); + CHECK_CONDVAR (cond); + cvar = XCONDVAR (cond); return cvar->mutex; } DEFUN ("condition-name", Fcondition_name, Scondition_name, 1, 1, 0, - doc: /* Return the name of CONDITION. -If no name was given when CONDITION was created, return nil. */) - (Lisp_Object condition) + doc: /* Return the name of condition variable COND. +If no name was given when COND was created, return nil. */) + (Lisp_Object cond) { struct Lisp_CondVar *cvar; - CHECK_CONDVAR (condition); - cvar = XCONDVAR (condition); + CHECK_CONDVAR (cond); + cvar = XCONDVAR (cond); return cvar->name; } @@ -678,7 +678,7 @@ finalize_one_thread (struct thread_state *state) DEFUN ("make-thread", Fmake_thread, Smake_thread, 1, 2, 0, doc: /* Start a new thread and run FUNCTION in it. When the function exits, the thread dies. -If NAME is given, it names the new thread. */) +If NAME is given, it must be a string; it names the new thread. */) (Lisp_Object function, Lisp_Object name) { sys_thread_t thr; @@ -843,8 +843,9 @@ thread_join_callback (void *arg) } DEFUN ("thread-join", Fthread_join, Sthread_join, 1, 1, 0, - doc: /* Wait for a thread to exit. -This blocks the current thread until THREAD exits. + doc: /* Wait for THREAD to exit. +This blocks the current thread until THREAD exits or until +the current thread is signaled. It is an error for a thread to try to join itself. */) (Lisp_Object thread) { @@ -863,7 +864,7 @@ It is an error for a thread to try to join itself. */) } DEFUN ("all-threads", Fall_threads, Sall_threads, 0, 0, 0, - doc: /* Return a list of all threads. */) + doc: /* Return a list of all the live threads. */) (void) { Lisp_Object result = Qnil; |