diff --git a/src/doc/new-doc/extensions/mp_ref.txi b/src/doc/new-doc/extensions/mp_ref.txi index 1f6f9df59..0ee671b22 100644 --- a/src/doc/new-doc/extensions/mp_ref.txi +++ b/src/doc/new-doc/extensions/mp_ref.txi @@ -1,282 +1,7 @@ @node Native threads reference @subsection Native threads reference -@node Processes -@subsubsection Processes -@c src/c/threads/process.d - -@cppindex mp_all_processes -@lspindex mp:all-processes - -@deftypefun cl_object mp_all_processes () -@end deftypefun - -@defun mp:all-processes - -Returns the list of processes associated to running tasks. The list is a -fresh new one and can be destructively modified. However, it may happen -that the output list is not up to date, because some of the tasks has -expired before this copy is returned. - -@end defun - - -@cppindex mp_exit_process -@lspindex mp:exit-process - -@deftypefun cl_object mp_all_processes () ecl_attr_noreturn -@end deftypefun - -@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 -invoking @code{ext:quit} with exit code 0. - -@end defun - - -@cppindex mp_interrupt_process -@lspindex mp:interrupt-process - -@deftypefun cl_object mp_interrupt_process (cl_object process, cl_object function) -@end deftypefun - -@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 -stop whatever it is doing and execute the given function. - -@exindex Process interruption -Example: - -Kill a task that is doing nothing (See @code{mp:process-kill}). - -@lisp -(flet ((task-to-be-killed () - ;; Infinite loop - (loop (sleep 1)))) - (let ((task (mp:process-run-function 'background #'task-to-be-killed))) - (sleep 10) - (mp:interrupt-process task 'mp:exit-process))) -@end lisp - -@end defun - - -@cppindex mp_make_process -@lspindex mp:make-process - -@deftypefun cl_object mp_make_process (cl_narg narg, ...) -@end deftypefun - -@defun mp:make-process &key name initial-bindings - -Create a new thread. This function creates a separate task with a name -set to @code {name}, set of variable bindings @code{initial-bindings} -and no function to run. See also @code{mp:process-run-function}. Returns -newly created process. - -@end defun - - -@cppindex mp_process_active_p -@lspindex mp:process-active-p - -@deftypefun cl_object mp_make_process (cl_object process) -@end deftypefun - -@defun mp:process-active-p process - -Returns @code{t} when @code{process} is active, @code {nil} -otherwise. Signals an error if @code{process} doesn't designate a valid -process. - -@end defun - - -@cppindex mp_process_enable -@lspindex mp:process-enable - -@deftypefun cl_object mp_process_enable (cl_object process) -@end deftypefun - -@defun mp:process-enable process - -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. - -@exindex Possible implementation of @code{mp:process-run-function}: - -@lisp -(defun process-run-function (process-name process-function &rest args) - (let ((process (mp:make-process name))) - (apply #'mp:process-preset process function args) - (mp:process-enable process))) -@end lisp -@end defun - - -@cppindex mp_process_yield -@lspindex mp:process_yield - -@deftypefun cl_object mp_process_yield () -@end deftypefun - -@defun mp:process-yield -Yield the processor to other threads. -@end defun - - -@cppindex 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. -@end defun - - -@cppindex mp_process_kill -@lspindex mp:process-kill - -@deftypefun cl_object mp_process_kill (cl_object process) -@end deftypefun - -@defun mp:process-kill process -Try to stop a running task. Killing a process may fail if the task has -disabled interrupts. - -@exindex Killing process -Example: - -Kill a task that is doing nothing -@lisp -(flet ((task-to-be-killed () - ;; Infinite loop - (loop (sleep 1)))) - (let ((task (mp:process-run-function 'background #'task-to-be-killed))) - (sleep 10) - (mp:process-kill task))) -@end lisp -@end defun - - -@cppindex mp_process_suspend -@lspindex mp:process-suspend - -@deftypefun cl_object mp_process_suspend (cl_object process) -@end deftypefun - -@defun mp:process-suspend process -Suspend a running @code{process}. May be resumed with -@code{mp:process-resume}. - -@exindex Suspend and resume process -Example: - -@lisp -(flet ((ticking-task () - ;; Infinite loop - (loop - (sleep 1) - (print :tick)))) - (print "Running task (one tick per second)") - (let ((task (mp:process-run-function 'background #'ticking-task))) - (sleep 5) - (print "Suspending task for 5 seconds") - (mp:process-suspend task) - (sleep 5) - (print "Resuming task for 5 seconds") - (mp:process-resume task) - (sleep 5) - (print "Killing task") - (mp:process-kill task))) -@end lisp -@end defun - - -@cppindex mp_process_resume -@lspindex mp:process-resume - -@deftypefun cl_object mp_process_resume (cl_object process) -@end deftypefun - -@defun mp:process-resume process -Resumes a suspended @code{process}. See example in -@code{mp:process-suspend}. -@end defun - - -@cppindex mp_process_name -@lspindex mp:process-name - -@deftypefun cl_object mp_process_name (cl_object process) -@end deftypefun - -@defun mp:process-name process -Returns the name of a @code{process} (if any). -@end defun - - -@cppindex mp_process_preset -@lspindex mp:process-preset - -@deftypefun cl_object mp_process_preset (cl_narg narg, cl_object process, cl_object function, ...) -@end deftypefun - -@defun mp:process-preset process function &rest function-args - -Associates a @code{function} to call with the arguments -@code{function-args}, with a stopped @code{process}. The function will -be the entry point when the task is enabled in the future. - -See @code{mp:enable-process} and @code{mp:process-run-function}. - -@end defun - - -@cppindex mp_process_run_function -@lspindex 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 -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 -Example: - -@lisp -(flet ((count-numbers (end-number) - (dotimes (i end-number) - (format t "~%;;; Counting: ~i" i) - (terpri) - (sleep 1)))) - (mp:process-run-function 'counter #'count-numbers 10)) -@end lisp -@end defun - - -@cppindex 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 +@include extensions/mp_ref_process.txi @c condition variables diff --git a/src/doc/new-doc/extensions/mp_ref_process.txi b/src/doc/new-doc/extensions/mp_ref_process.txi new file mode 100644 index 000000000..9707367e8 --- /dev/null +++ b/src/doc/new-doc/extensions/mp_ref_process.txi @@ -0,0 +1,276 @@ +@node Processes +@subsubsection Processes +@c src/c/threads/process.d + +@cppindex mp_all_processes +@lspindex mp:all-processes + +@deftypefun cl_object mp_all_processes () +@end deftypefun + +@defun mp:all-processes + +Returns the list of processes associated to running tasks. The list is a +fresh new one and can be destructively modified. However, it may happen +that the output list is not up to date, because some of the tasks has +expired before this copy is returned. + +@end defun + + +@cppindex mp_exit_process +@lspindex mp:exit-process + +@deftypefun cl_object mp_all_processes () ecl_attr_noreturn +@end deftypefun + +@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 +invoking @code{ext:quit} with exit code 0. + +@end defun + + +@cppindex mp_interrupt_process +@lspindex mp:interrupt-process + +@deftypefun cl_object mp_interrupt_process (cl_object process, cl_object function) +@end deftypefun + +@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 +stop whatever it is doing and execute the given function. + +@exindex Process interruption +Example: + +Kill a task that is doing nothing (See @code{mp:process-kill}). + +@lisp +(flet ((task-to-be-killed () + ;; Infinite loop + (loop (sleep 1)))) + (let ((task (mp:process-run-function 'background #'task-to-be-killed))) + (sleep 10) + (mp:interrupt-process task 'mp:exit-process))) +@end lisp + +@end defun + + +@cppindex mp_make_process +@lspindex mp:make-process + +@deftypefun cl_object mp_make_process (cl_narg narg, ...) +@end deftypefun + +@defun mp:make-process &key name initial-bindings + +Create a new thread. This function creates a separate task with a name +set to @code {name}, set of variable bindings @code{initial-bindings} +and no function to run. See also @code{mp:process-run-function}. Returns +newly created process. + +@end defun + + +@cppindex mp_process_active_p +@lspindex mp:process-active-p + +@deftypefun cl_object mp_make_process (cl_object process) +@end deftypefun + +@defun mp:process-active-p process + +Returns @code{t} when @code{process} is active, @code {nil} +otherwise. Signals an error if @code{process} doesn't designate a valid +process. + +@end defun + + +@cppindex mp_process_enable +@lspindex mp:process-enable + +@deftypefun cl_object mp_process_enable (cl_object process) +@end deftypefun + +@defun mp:process-enable process + +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. + +@exindex Possible implementation of @code{mp:process-run-function}: + +@lisp +(defun process-run-function (process-name process-function &rest args) + (let ((process (mp:make-process name))) + (apply #'mp:process-preset process function args) + (mp:process-enable process))) +@end lisp +@end defun + + +@cppindex mp_process_yield +@lspindex mp:process_yield + +@deftypefun cl_object mp_process_yield () +@end deftypefun + +@defun mp:process-yield +Yield the processor to other threads. +@end defun + + +@cppindex 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. +@end defun + + +@cppindex mp_process_kill +@lspindex mp:process-kill + +@deftypefun cl_object mp_process_kill (cl_object process) +@end deftypefun + +@defun mp:process-kill process +Try to stop a running task. Killing a process may fail if the task has +disabled interrupts. + +@exindex Killing process +Example: + +Kill a task that is doing nothing +@lisp +(flet ((task-to-be-killed () + ;; Infinite loop + (loop (sleep 1)))) + (let ((task (mp:process-run-function 'background #'task-to-be-killed))) + (sleep 10) + (mp:process-kill task))) +@end lisp +@end defun + + +@cppindex mp_process_suspend +@lspindex mp:process-suspend + +@deftypefun cl_object mp_process_suspend (cl_object process) +@end deftypefun + +@defun mp:process-suspend process +Suspend a running @code{process}. May be resumed with +@code{mp:process-resume}. + +@exindex Suspend and resume process +Example: + +@lisp +(flet ((ticking-task () + ;; Infinite loop + (loop + (sleep 1) + (print :tick)))) + (print "Running task (one tick per second)") + (let ((task (mp:process-run-function 'background #'ticking-task))) + (sleep 5) + (print "Suspending task for 5 seconds") + (mp:process-suspend task) + (sleep 5) + (print "Resuming task for 5 seconds") + (mp:process-resume task) + (sleep 5) + (print "Killing task") + (mp:process-kill task))) +@end lisp +@end defun + + +@cppindex mp_process_resume +@lspindex mp:process-resume + +@deftypefun cl_object mp_process_resume (cl_object process) +@end deftypefun + +@defun mp:process-resume process +Resumes a suspended @code{process}. See example in +@code{mp:process-suspend}. +@end defun + + +@cppindex mp_process_name +@lspindex mp:process-name + +@deftypefun cl_object mp_process_name (cl_object process) +@end deftypefun + +@defun mp:process-name process +Returns the name of a @code{process} (if any). +@end defun + + +@cppindex mp_process_preset +@lspindex mp:process-preset + +@deftypefun cl_object mp_process_preset (cl_narg narg, cl_object process, cl_object function, ...) +@end deftypefun + +@defun mp:process-preset process function &rest function-args + +Associates a @code{function} to call with the arguments +@code{function-args}, with a stopped @code{process}. The function will +be the entry point when the task is enabled in the future. + +See @code{mp:enable-process} and @code{mp:process-run-function}. + +@end defun + + +@cppindex mp_process_run_function +@lspindex 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 +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 +Example: + +@lisp +(flet ((count-numbers (end-number) + (dotimes (i end-number) + (format t "~%;;; Counting: ~i" i) + (terpri) + (sleep 1)))) + (mp:process-run-function 'counter #'count-numbers 10)) +@end lisp +@end defun + + +@cppindex 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