summaryrefslogtreecommitdiff
path: root/doc/ref/api-evaluation.texi
diff options
context:
space:
mode:
authorDavid Thompson <dthompson2@worcester.edu>2014-01-19 13:16:02 -0500
committerMark H Weaver <mhw@netris.org>2014-02-12 11:26:22 -0500
commitb0a31499554fb69160b18ccefac89eec4954e488 (patch)
tree9bfce8b7d703e266d1dad07ca6c1a8a1b666af7a /doc/ref/api-evaluation.texi
parent5ecc58113a0a50d7a5840e9bfccce25b4f8b30ce (diff)
downloadguile-b0a31499554fb69160b18ccefac89eec4954e488.tar.gz
Add cooperative REPL server module.
Modified-by: Mark H Weaver <mhw@netris.org> * module/system/repl/coop-server.scm: New module. * module/system/repl/repl.scm (start-repl): Extract body to start-repl*. (start-repl*): New procedure. (run-repl): Extract body to run-repl*. (run-repl*): New procedure. * module/system/repl/server.scm (run-server): Extract body to run-server*. (run-server*): New procedure. * doc/ref/api-evaluation.texi (Cooperative REPL Servers): New node. * module/Makefile.am (SYSTEM_SOURCES): Add system/repl/coop-server.scm.
Diffstat (limited to 'doc/ref/api-evaluation.texi')
-rw-r--r--doc/ref/api-evaluation.texi45
1 files changed, 45 insertions, 0 deletions
diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi
index d3e6c8cbb..c441dffee 100644
--- a/doc/ref/api-evaluation.texi
+++ b/doc/ref/api-evaluation.texi
@@ -23,6 +23,7 @@ loading, evaluating, and compiling Scheme code at run time.
* Local Evaluation:: Evaluation in a local lexical environment.
* Local Inclusion:: Compile-time inclusion of one file in another.
* REPL Servers:: Serving a REPL over a socket.
+* Cooperative REPL Servers:: REPL server for single-threaded applications.
@end menu
@@ -1285,6 +1286,50 @@ cancelled without unwinding their stacks. If any of them are holding
mutexes or are within a critical section, the results are unspecified.
@end deffn
+@node Cooperative REPL Servers
+@subsection Cooperative REPL Servers
+
+@cindex Cooperative REPL server
+
+The procedures in this section are provided by
+@lisp
+(use-modules (system repl coop-server))
+@end lisp
+
+Whereas ordinary REPL servers run in their own threads (@pxref{REPL
+Servers}), sometimes it is more convenient to provide REPLs that run at
+specified times within an existing thread, for example in programs
+utilizing an event loop or in single-threaded programs. This allows for
+safe access and mutation of a program's data structures from the REPL,
+without concern for thread synchronization.
+
+Although the REPLs are run in the thread that calls
+@code{spawn-coop-repl-server} and @code{poll-coop-repl-server},
+dedicated threads are spawned so that the calling thread is not blocked.
+The spawned threads read input for the REPLs and to listen for new
+connections.
+
+Cooperative REPL servers must be polled periodically to evaluate any
+pending expressions by calling @code{poll-coop-repl-server} with the
+object returned from @code{spawn-coop-repl-server}. The thread that
+calls @code{poll-coop-repl-server} will be blocked for as long as the
+expression takes to be evaluated or if the debugger is entered.
+
+@deffn {Scheme Procedure} spawn-coop-repl-server [server-socket]
+Create and return a new cooperative REPL server object, and spawn a new
+thread to listen for connections on @var{server-socket}. Proper
+functioning of the REPL server requires that
+@code{poll-coop-repl-server} be called periodically on the returned
+server object.
+@end deffn
+
+@deffn {Scheme Procedure} poll-coop-repl-server coop-server
+Poll the cooperative REPL server @var{coop-server} and apply a pending
+operation if there is one, such as evaluating an expression typed at the
+REPL prompt. This procedure must be called from the same thread that
+called @code{spawn-coop-repl-server}.
+@end deffn
+
@c Local Variables:
@c TeX-master: "guile.texi"
@c End: