2756184d997a16ba67659b28b6f27579e71dac4b
[projects/qitab/single-threaded-ccl.git] / README
1 SINGLE-THREADED-CCL
2 ===================
3
4 A simple patch to allow Clozure CL (CCL) to run in single-threaded mode.
5
6 This is free software, available under the same license as CCL, LLGPL 2.1.
7
8
9 Using It
10 --------
11
12 To create a single-threaded ccl, you may::
13
14         ${CCL_DEFAULT_DIRECTORY}/lx86cl64 --no-init --load make-single-threaded-ccl
15
16
17 To test that indeed you can run code single-threaded mode, you may::
18
19         ./single-threaded-ccl --eval '(progn (format t "~S" ccl::*application*) (ccl::show-processes) (ccl:quit))'
20
21 It your CCL is successfully single-threaded, only one process will show.
22
23
24 Note that to be able to use many of the dynamically loaded features of CCL,
25 you will need to either put your single-threaded-ccl in the same directory
26 as the rest of CCL and use it from there, or you will need to::
27
28         export CCL_DEFAULT_DIRECTORY=/path/to/original-ccl
29
30
31 If you build with ASDF, you may also depend on the system single-threaded-ccl,
32 and when you next save an image, it will start single-threaded.
33
34
35 Last Tested
36 -----------
37
38 It was last tested to run with this checkout of CCL, revision 15791.
39         http://svn.clozure.com/publicsvn/openmcl/trunk/linuxx86/ccl
40
41
42 Won't Make It Upstream
43 ----------------------
44
45 This was submitted for inclusion in the upstream CCL distribution.
46 However, Gary Byers has expressed his disinterest in offering and maintaining
47 an option for single-threaded startup in the upstream CCL,
48 even when I proposed that I could do the porting and maintaining myself.
49
50
51
52 Why We Need It
53 --------------
54
55 CCL by default starts ancillary threads early during initialization,
56 which makes any subsequent attempt to use fork
57 almost guaranteed to lead to massive instability
58 (unless maybe it's promptly followed by exec, as in run-program,
59 without a GC interrupt in between).
60 See my blog post:
61         http://fare.livejournal.com/148185.html
62
63 However, I have been maintaining this "single-threaded CCL" modification
64 that can create an image of CCL that doesn't start these ancillary threads
65 (at the cost of having to manually flush output streams and
66 of not being able to interrupt computations interactively with Ctrl-C).
67
68 I use this single-threaded CCL for parallel build with POIU and XCVB,
69 and have had to update it once in a while
70 as upstream upgrades sometimes break it.
71 I also intend to use it in other situations
72 where fork-based concurrency is called for:
73 pre-forking servers, robust erlang-style concurrency,
74 isolating semi-trusted C libraries, etc.