diff options
author | Neil Jerram <neil@ossau.uklinux.net> | 2001-11-16 15:04:17 +0000 |
---|---|---|
committer | Neil Jerram <neil@ossau.uklinux.net> | 2001-11-16 15:04:17 +0000 |
commit | 8f85c0c6c3eb8de857babc08ca6e832e8a497c44 (patch) | |
tree | bb9e336486e81b1733fc2d8c30088be6c3c01096 /doc/ref/scheme-scheduling.texi | |
parent | cecb4a5e9dbaebcc28f3be0a02feac4263a2cfcc (diff) | |
download | guile-8f85c0c6c3eb8de857babc08ca6e832e8a497c44.tar.gz |
* Adding C function declarations from the SCM interface to the
reference manual documentation.
Diffstat (limited to 'doc/ref/scheme-scheduling.texi')
-rw-r--r-- | doc/ref/scheme-scheduling.texi | 80 |
1 files changed, 49 insertions, 31 deletions
diff --git a/doc/ref/scheme-scheduling.texi b/doc/ref/scheme-scheduling.texi index e2cdd3d2a..920a73029 100644 --- a/doc/ref/scheme-scheduling.texi +++ b/doc/ref/scheme-scheduling.texi @@ -30,18 +30,21 @@ otherwise it will fail and return @code{#f}. Once an arbiter is successfully locked, it cannot be locked by another thread until the thread holding the arbiter calls @code{release-arbiter} to unlock it. -@deffn primitive make-arbiter name +@deffn {Scheme Procedure} make-arbiter name +@deffnx {C Function} scm_make_arbiter (name) Return an object of type arbiter and name @var{name}. Its state is initially unlocked. Arbiters are a way to achieve process synchronization. @end deffn -@deffn primitive try-arbiter arb +@deffn {Scheme Procedure} try-arbiter arb +@deffnx {C Function} scm_try_arbiter (arb) Return @code{#t} and lock the arbiter @var{arb} if the arbiter was unlocked. Otherwise, return @code{#f}. @end deffn -@deffn primitive release-arbiter arb +@deffn {Scheme Procedure} release-arbiter arb +@deffnx {C Function} scm_release_arbiter (arb) Return @code{#t} and unlock the arbiter @var{arb} if the arbiter was locked. Otherwise, return @code{#f}. @end deffn @@ -70,20 +73,24 @@ Normal asyncs are created with @code{async}, system asyncs with @code{system-async}. They are marked with @code{async-mark} or @code{system-async-mark}, respectively. -@deffn primitive async thunk +@deffn {Scheme Procedure} async thunk +@deffnx {C Function} scm_async (thunk) Create a new async for the procedure @var{thunk}. @end deffn -@deffn primitive system-async thunk +@deffn {Scheme Procedure} system-async thunk +@deffnx {C Function} scm_system_async (thunk) Create a new async for the procedure @var{thunk}. Also add it to the system's list of active async objects. @end deffn -@deffn primitive async-mark a +@deffn {Scheme Procedure} async-mark a +@deffnx {C Function} scm_async_mark (a) Mark the async @var{a} for future execution. @end deffn -@deffn primitive system-async-mark a +@deffn {Scheme Procedure} system-async-mark a +@deffnx {C Function} scm_system_async_mark (a) Mark the async @var{a} for future execution. @end deffn @@ -91,7 +98,8 @@ As already mentioned above, system asyncs are executed automatically. Normal asyncs have to be explicitly invoked by storing one or more of them into a list and passing them to @code{run-asyncs}. -@deffn primitive run-asyncs list_of_a +@deffn {Scheme Procedure} run-asyncs list_of_a +@deffnx {C Function} scm_run_asyncs (list_of_a) Execute all thunks from the asyncs of the list @var{list_of_a}. @end deffn @@ -102,18 +110,21 @@ run once execution is enabled again. Please note that calls to these procedures should always be paired, and they must not be nested, e.g. no @code{mask-signals} is allowed if another one is still active. -@deffn primitive mask-signals +@deffn {Scheme Procedure} mask-signals +@deffnx {C Function} scm_mask_signals () Mask signals. The returned value is not specified. @end deffn -@deffn primitive unmask-signals +@deffn {Scheme Procedure} unmask-signals +@deffnx {C Function} scm_unmask_signals () Unmask signals. The returned value is not specified. @end deffn @c FIXME::martin: Find an example for usage of `noop'. What is that @c procedure for anyway? -@deffn primitive noop . args +@deffn {Scheme Procedure} noop . args +@deffnx {C Function} scm_noop (args) Do nothing. When called without arguments, return @code{#f}, otherwise return the first argument. @end deffn @@ -139,7 +150,8 @@ dynamic root. For example, if you want to apply a procedure, but to not allow that procedure to capture the current continuation, calling the procedure under a new dynamic root will do the job. -@deffn primitive call-with-dynamic-root thunk handler +@deffn {Scheme Procedure} call-with-dynamic-root thunk handler +@deffnx {C Function} scm_call_with_dynamic_root (thunk, handler) Evaluate @code{(thunk)} in a new dynamic context, returning its value. If an error occurs during evaluation, apply @var{handler} to the @@ -185,7 +197,8 @@ be under a new dynamic root.) @end deffn -@deffn primitive dynamic-root +@deffn {Scheme Procedure} dynamic-root +@deffnx {C Function} scm_dynamic_root () Return an object representing the current dynamic root. These objects are only useful for comparison using @code{eq?}. @@ -194,7 +207,7 @@ in no way depend on this. @end deffn @c begin (scm-doc-string "boot-9.scm" "quit") -@deffn procedure quit [exit_val] +@deffn {Scheme Procedure} quit [exit_val] Throw back to the error handler of the current dynamic root. If integer @var{exit_val} is specified and if Guile is being used @@ -215,12 +228,12 @@ from Scheme code to be removed. An example of where this is useful is after forking a new process intended to run non-interactively. @c begin (scm-doc-string "boot-9.scm" "batch-mode?") -@deffn procedure batch-mode? +@deffn {Scheme Procedure} batch-mode? Returns a boolean indicating whether the interpreter is in batch mode. @end deffn @c begin (scm-doc-string "boot-9.scm" "set-batch-mode?!") -@deffn procedure set-batch-mode?! arg +@deffn {Scheme Procedure} set-batch-mode?! arg If @var{arg} is true, switches the interpreter to batch mode. The @code{#f} case has not been implemented. @end deffn @@ -258,7 +271,7 @@ executed in a new dynamic root. @c are in sync. @c begin (texi-doc-string "guile" "call-with-new-thread") -@deffn primitive call-with-new-thread thunk error-handler +@deffn {Scheme Procedure} call-with-new-thread thunk error-handler Evaluate @code{(thunk)} in a new thread, and new dynamic context, returning a new thread object representing the thread. @@ -273,31 +286,31 @@ All the evaluation rules for dynamic roots apply to threads. @end deffn @c begin (texi-doc-string "guile" "join-thread") -@deffn primitive join-thread thread +@deffn {Scheme Procedure} join-thread thread Suspend execution of the calling thread until the target @var{thread} terminates, unless the target @var{thread} has already terminated. @end deffn @c begin (texi-doc-string "guile" "yield") -@deffn primitive yield +@deffn {Scheme Procedure} yield If one or more threads are waiting to execute, calling yield forces an immediate context switch to one of them. Otherwise, yield has no effect. @end deffn @c begin (texi-doc-string "guile" "make-mutex") -@deffn primitive make-mutex +@deffn {Scheme Procedure} make-mutex Create a new mutex object. @end deffn @c begin (texi-doc-string "guile" "lock-mutex") -@deffn primitive lock-mutex mutex +@deffn {Scheme Procedure} lock-mutex mutex Lock @var{mutex}. If the mutex is already locked, the calling thread blocks until the mutex becomes available. The function returns when the calling thread owns the lock on @var{mutex}. @end deffn @c begin (texi-doc-string "guile" "unlock-mutex") -@deffn primitive unlock-mutex mutex +@deffn {Scheme Procedure} unlock-mutex mutex Unlocks @var{mutex} if the calling thread owns the lock on @var{mutex}. Calling unlock-mutex on a mutex not owned by the current thread results in undefined behaviour. Once a mutex has been unlocked, one thread @@ -305,15 +318,15 @@ blocked on @var{mutex} is awakened and grabs the mutex lock. @end deffn @c begin (texi-doc-string "guile" "make-condition-variable") -@deffn primitive make-condition-variable +@deffn {Scheme Procedure} make-condition-variable @end deffn @c begin (texi-doc-string "guile" "wait-condition-variable") -@deffn primitive wait-condition-variable cond-var mutex +@deffn {Scheme Procedure} wait-condition-variable cond-var mutex @end deffn @c begin (texi-doc-string "guile" "signal-condition-variable") -@deffn primitive signal-condition-variable cond-var +@deffn {Scheme Procedure} signal-condition-variable cond-var @end deffn @@ -326,7 +339,7 @@ Higher level thread procedures are available by loading the @code{(ice-9 threads)} module. These provide standardized thread creation and mutex interaction. -@deffn primitive %thread-handler tag args@dots{} +@deffn {Scheme Procedure} %thread-handler tag args@dots{} This procedure is specified as the standard error-handler for @code{make-thread} and @code{begin-thread}. If the number of @var{args} @@ -390,7 +403,8 @@ in Scheme---this cannot happen. See the description of New fluids are created with @code{make-fluid} and @code{fluid?} is used for testing whether an object is actually a fluid. -@deffn primitive make-fluid +@deffn {Scheme Procedure} make-fluid +@deffnx {C Function} scm_make_fluid () Return a newly created fluid. Fluids are objects of a certain type (a smob) that can hold one SCM value per dynamic root. That is, modifications to this value are @@ -400,7 +414,8 @@ inherits the values from its parent. Because each thread executes in its own dynamic root, you can use fluids for thread local storage. @end deffn -@deffn primitive fluid? obj +@deffn {Scheme Procedure} fluid? obj +@deffnx {C Function} scm_fluid_p (obj) Return @code{#t} iff @var{obj} is a fluid; otherwise, return @code{#f}. @end deffn @@ -408,13 +423,15 @@ Return @code{#t} iff @var{obj} is a fluid; otherwise, return The values stored in a fluid can be accessed with @code{fluid-ref} and @code{fluid-set!}. -@deffn primitive fluid-ref fluid +@deffn {Scheme Procedure} fluid-ref fluid +@deffnx {C Function} scm_fluid_ref (fluid) Return the value associated with @var{fluid} in the current dynamic root. If @var{fluid} has not been set, then return @code{#f}. @end deffn -@deffn primitive fluid-set! fluid value +@deffn {Scheme Procedure} fluid-set! fluid value +@deffnx {C Function} scm_fluid_set_x (fluid, value) Set the value associated with @var{fluid} in the current dynamic root. @end deffn @@ -422,7 +439,8 @@ Set the value associated with @var{fluid} in the current dynamic root. so that the given procedure and each procedure called by it access the given values. After the procedure returns, the old values are restored. -@deffn primitive with-fluids* fluids values thunk +@deffn {Scheme Procedure} with-fluids* fluids values thunk +@deffnx {C Function} scm_with_fluids (fluids, values, thunk) Set @var{fluids} to @var{values} temporary, and call @var{thunk}. @var{fluids} must be a list of fluids and @var{values} must be the same number of their values to be applied. Each substitution is done |