summaryrefslogtreecommitdiff
path: root/doc/ref/scheme-scheduling.texi
diff options
context:
space:
mode:
authorNeil Jerram <neil@ossau.uklinux.net>2001-11-16 15:04:17 +0000
committerNeil Jerram <neil@ossau.uklinux.net>2001-11-16 15:04:17 +0000
commit8f85c0c6c3eb8de857babc08ca6e832e8a497c44 (patch)
treebb9e336486e81b1733fc2d8c30088be6c3c01096 /doc/ref/scheme-scheduling.texi
parentcecb4a5e9dbaebcc28f3be0a02feac4263a2cfcc (diff)
downloadguile-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.texi80
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