From 8ad10cec50916badadeff7bd05ac3b04d20f3e53 Mon Sep 17 00:00:00 2001 From: Marius Gerbershagen Date: Wed, 17 Oct 2018 21:52:19 +0200 Subject: [PATCH] doc: fix some typos and errors in the multithreading documentation --- src/doc/new-doc/extensions/mp_ref_atomic.txi | 18 ++++++----- src/doc/new-doc/extensions/mp_ref_barrier.txi | 2 +- src/doc/new-doc/extensions/mp_ref_mutex.txi | 4 +-- src/doc/new-doc/extensions/mp_ref_process.txi | 30 +++++++++---------- src/doc/new-doc/extensions/mp_ref_rwlock.txi | 6 ++-- src/doc/new-doc/extensions/mp_ref_sem.txi | 6 ++-- 6 files changed, 34 insertions(+), 32 deletions(-) diff --git a/src/doc/new-doc/extensions/mp_ref_atomic.txi b/src/doc/new-doc/extensions/mp_ref_atomic.txi index eb91570db..9e812011d 100644 --- a/src/doc/new-doc/extensions/mp_ref_atomic.txi +++ b/src/doc/new-doc/extensions/mp_ref_atomic.txi @@ -10,35 +10,37 @@ similar to @code{setf}. @subsubheading C Reference @cppindex ecl_compare_and_swap -@deftypefun cl_object ecl_compare_and_swap(cl_object *slot, cl_object old, cl_object new) +@deftypefun cl_object ecl_compare_and_swap (cl_object *slot, cl_object old, cl_object new) Perform an atomic compare and swap operation on @var{slot} and return the previous value stored in @var{slot}. If the return value is equal to @var{old} (comparison by @code{==}), the operation has succeeded. +This is a inline-only function defined in ``ecl/ecl_atomics.h''. @end deftypefun @cppindex ecl_atomic_incf -@deftypefun cl_object ecl_atomic_incf(cl_object *slot, cl_object increment) +@deftypefun cl_object ecl_atomic_incf (cl_object *slot, cl_object increment) @end deftypefun @cppindex ecl_atomic_incf_by_fixnum -@deftypefun cl_object ecl_atomic_incf_by_fixnum(cl_object *slot, cl_fixnum increment) +@deftypefun cl_object ecl_atomic_incf_by_fixnum (cl_object *slot, cl_fixnum increment) Atomically increment @var{slot} by the given increment and return the previous value stored in @var{slot}. The consequences are undefined if the value of @var{slot} is not of type @code{fixnum}. @code{ecl_atomic_incf} signals an error if @var{increment} is not of -type @code{fixnum}. . +type @code{fixnum}. This is a inline-only function defined in +``ecl/ecl_atomics.h''. @end deftypefun @cppindex ecl_atomic_index_incf -@deftypefun cl_index ecl_atomic_index_incf(cl_index *slot); +@deftypefun cl_index ecl_atomic_index_incf (cl_index *slot); Atomically increment @var{slot} by 1 and return the new value stored in @var{slot}. @end deftypefun @cppindex ecl_atomic_get -@deftypefun cl_object ecl_atomic_get(cl_object *slot) +@deftypefun cl_object ecl_atomic_get (cl_object *slot) Perform a volatile load of the object in @var{slot} and then atomically set @var{slot} to @code{ECL_NIL}. Returns the value @@ -46,10 +48,10 @@ previously stored in @var{slot}. @end deftypefun @cppindex ecl_atomic_push -@deftypefun void ecl_atomic_push(cl_object *slot, cl_object o) +@deftypefun void ecl_atomic_push (cl_object *slot, cl_object o) @end deftypefun @cppindex ecl_atomic_pop -@deftypefun cl_object ecl_atomic_pop(cl_object *slot) +@deftypefun cl_object ecl_atomic_pop (cl_object *slot) Like push/pop but atomic. @end deftypefun diff --git a/src/doc/new-doc/extensions/mp_ref_barrier.txi b/src/doc/new-doc/extensions/mp_ref_barrier.txi index 6d61ff63f..9007206e0 100644 --- a/src/doc/new-doc/extensions/mp_ref_barrier.txi +++ b/src/doc/new-doc/extensions/mp_ref_barrier.txi @@ -23,7 +23,7 @@ mp:barrier-count @lspindex mp:barrier-name cl_object mp_barrier_name (cl_object) -mp:barrier_name +mp:barrier-name @cppindex mp_barrier_arrivers_count diff --git a/src/doc/new-doc/extensions/mp_ref_mutex.txi b/src/doc/new-doc/extensions/mp_ref_mutex.txi index a990bc6b4..caa324134 100644 --- a/src/doc/new-doc/extensions/mp_ref_mutex.txi +++ b/src/doc/new-doc/extensions/mp_ref_mutex.txi @@ -89,7 +89,7 @@ Returns number of processes waiting for @code{lock}. @lspindex mp:get-lock @deftypefun cl_object mp_get_lock_wait (cl_object lock) -Grabs a lock (blocking if @code{lock} is already takene). Returns +Grabs a lock (blocking if @code{lock} is already taken). Returns @code{ECL_T}. @end deftypefun @@ -112,7 +112,7 @@ block or give up if @code{lock} is already taken. If @code{wait} is @deftypefun cl_object mp_giveup_lock (cl_object lock) @end deftypefun -@defun mp:giveup_lock +@defun mp:giveup_lock lock Releases @code{lock}. @end defun diff --git a/src/doc/new-doc/extensions/mp_ref_process.txi b/src/doc/new-doc/extensions/mp_ref_process.txi index 82b8bb3a2..abba6cf35 100644 --- a/src/doc/new-doc/extensions/mp_ref_process.txi +++ b/src/doc/new-doc/extensions/mp_ref_process.txi @@ -25,10 +25,10 @@ expired before this copy is returned. @cppindex mp_exit_process @lspindex mp:exit-process -@deftypefun cl_object mp_all_processes () ecl_attr_noreturn +@deftypefun cl_object mp_exit_process () ecl_attr_noreturn @end deftypefun -@defun mp:exit_process +@defun mp:exit-process When called from a running task, this function immediately causes the task to finish. When invoked from the main thread, it is equivalent to @@ -43,7 +43,7 @@ invoking @code{ext:quit} with exit code 0. @deftypefun cl_object mp_interrupt_process (cl_object process, cl_object function) @end deftypefun -@defun mp:interrupt_process process function +@defun mp:interrupt-process process function Interrupt a task. This @code{function} sends a signal to a running @code{process}. When the task is free to process that signal, it will @@ -85,7 +85,7 @@ newly created process. @cppindex mp_process_active_p @lspindex mp:process-active-p -@deftypefun cl_object mp_make_process (cl_object process) +@deftypefun cl_object mp_process_active_p (cl_object process) @end deftypefun @defun mp:process-active-p process @@ -109,7 +109,8 @@ The argument to this function should be a process created by @code{mp:make-process}, which has a function associated as per @code{mp:process-preset} but which is not yet running. After invoking this function a new thread will be created in which the associated -function will be executed. +function will be executed. Returns @code{process} if the thread +creation was successful and @code{nil} otherwise. @exindex Possible implementation of @code{mp:process-run-function}: @@ -123,7 +124,7 @@ function will be executed. @cppindex mp_process_yield -@lspindex mp:process_yield +@lspindex mp:process-yield @deftypefun cl_object mp_process_yield () @end deftypefun @@ -134,15 +135,14 @@ Yield the processor to other threads. @cppindex mp_process-join -@lspindex mp:process_join +@lspindex mp:process-join @deftypefun cl_object mp_process_join (cl_object process) @end deftypefun @defun mp:process-join process Suspend current thread until @code{process} exits. Return the result -values of the @code{process} function. If @code{process} is the current -thread, signal an error with. +values of the @code{process} function. @end defun @@ -251,11 +251,11 @@ See @code{mp:enable-process} and @code{mp:process-run-function}. @deftypefun cl_object mp_process_run_function (cl_narg narg, cl_object name, cl_object function, ...) @end deftypefun -@defun mp:process_run_function name function &rest funciton-args +@defun mp:process-run-function name function &rest function-args Create a new process using @code{mp:make-process}, associate a function to it and start it using @code{mp:process-preset}. -@exindex mp:process-run-funciton usage +@exindex mp:process-run-function usage Example: @lisp @@ -270,14 +270,14 @@ Example: @cppindex mp_current_process -@lspindex mp:current_process +@lspindex mp:*current-process* @deftypefun cl_object mp_current_process () @end deftypefun -@defun mp:current-process -Returns the current process of a caller. -@end defun +@defvr {mp} {*current-process*} +Returns/holds the current process of a caller. +@end defvr @cppindex mp_block_signals diff --git a/src/doc/new-doc/extensions/mp_ref_rwlock.txi b/src/doc/new-doc/extensions/mp_ref_rwlock.txi index 8d0d20c2a..9461d0a9c 100644 --- a/src/doc/new-doc/extensions/mp_ref_rwlock.txi +++ b/src/doc/new-doc/extensions/mp_ref_rwlock.txi @@ -52,7 +52,7 @@ readers). Returns @code{ECL_T}. @end deftypefun @deftypefun cl_object mp_get_rwlock_read_nowait -Tries to acquire @code{lock}. if @code{lock} is already taken with +Tries to acquire @code{lock}. If @code{lock} is already taken with @code{mp:get-rwlock-write} returns @code{ECL_NIL}, otherwise @code{ECL_T}. @end deftypefun @@ -96,9 +96,9 @@ should block or give up if @code{lock} is already taken. @deftypefun cl_object mp_giveup_rwlock_write (cl_object lock) @end deftypefun -@defun mp:giveup_rwlock_read lock +@defun mp:giveup-rwlock-read lock @end defun -@defun mp:giveup_rwlock_write lock +@defun mp:giveup-rwlock-write lock Release @code{lock}. @end defun diff --git a/src/doc/new-doc/extensions/mp_ref_sem.txi b/src/doc/new-doc/extensions/mp_ref_sem.txi index cdedf464c..6d95846a6 100644 --- a/src/doc/new-doc/extensions/mp_ref_sem.txi +++ b/src/doc/new-doc/extensions/mp_ref_sem.txi @@ -19,7 +19,7 @@ See @code{mp:make-sempahore}. @cppindex mp_make_semaphore -@lspindex mp:make_semaphore +@lspindex mp:make-semaphore @defun mp:make-semaphore &key name count Creates a counting semaphore @code{name} with a resource count @@ -78,9 +78,9 @@ resource count before semaphore was acquired. @deftypefun cl_object mp_try_get_semaphore (cl_object semaphore) @end deftypefun -@defun mp:try_get_semaphore semaphore +@defun mp:try-get-semaphore semaphore Tries to get a semaphore (non-blocking). If there is no resource left -returns @code{NIL}, otherwise returns resource count before semaphore +returns @code{nil}, otherwise returns resource count before semaphore was acquired. @end defun