3 (we are really in muse mode; but most people don't have it readily
4 available and we aren't forcing the use of Emacs/muse. M-x muse-mode
5 makes reading easier IMHO).
10 See the file COPYING in the top level directory.
12 * Interfacing Common Lisp and R
14 This library considers multiple approaches for connecting Common Lisp
15 and R, particularly for embedding R within CL. CLSR also attempts to
16 do the reverse. RCL is a third approach, which provides more
17 porcelain around the plumbing. RCLG also tries to use R with the
18 threaded SBCL capability. All of this will be commented on later (in
26 You will need the following libraries available:
28 1. ASDF (system definition facility, for loading packages)
29 2. CFFI (Common foreign function interface: later than CFFI-060526)
31 3. RCLG (this library)
35 Once you have these, then the simple way to get started is to:
37 1. add rclg.asd to the ASDF systems path.
38 2. See rclg-demo.lisp for getting started. It has incantations for:
39 a. compiling and loading cffi
40 b. compiling and loading rclg
42 d. basic data conversion.
53 * Past and possibly present "Issues"
55 ** From the file formerly known as NOTES/06032006.rif (date contained)
57 1. In the current version of cffi, the variable names get wrapped in
60 (defcvar "R_CStackLimit" :unsigned-long) ;; :unsigned long
61 (defcvar "R_SignalHandlers" :unsigned-long) ;; :unsigned long
63 make variables named *R-CSTACKLIMIT* and *R-SIGNALHANDLERS*
65 2. In "rclg-demo.lisp", I wanted to mention that rnb doesn't mean "no
66 blocking", it means "no backconverting". It's not that it doesn't
67 protect --- it does all the normal protection, it just doesn't
68 convert the result back from R to Lisp. It's to avoid pushing big
69 objects back and forth through the pipe needlessly. In some sense,
70 rnb is what you'd use to do an R assignment, but you get a CL name
71 for whatever it is rather than an R name.
73 3. At this point, it seems like setting *R-SIGNALHANDLERS* to 0 is
74 preventing an immediate seg fault. So that's good.
76 4. We are still getting errors related to the stack, and I can't
77 actually *find* anything. Whenever I try to find a function, I'm
78 getting back "Unbound value". I don't know for sure that this is
79 related to the stack problems. The equivalent C program does find
80 things. I've put the C and Lisp programs in subdirectory
81 simple-test. I'm not sure whether want to be using Rf_findVar or
84 5. I'm not sure 100% I'm handling the stack correctly. On the mailing
85 list, it suggests setting R_CStackLimit = -1. However, CFFI
86 believes that *R-CSTACKLIMIT* is an unsigned long, and won't let me
87 set it to -1. I'm seting it to the two's complement value, which
88 is 429476295. I think this is OK, but tell me if it isn't.
90 6. It is worth noting that Rf_initEmbeddedR *will* change the value of
91 R_CStackLimit. So it is important to set signalhandlers to 0
92 BEFORE starting R, and then probably set StackLimit afterwards.
93 I've played a bit with going into the R source and turning off the
94 stuff in the initialization that sets it to some value, but that
95 produced an infinite loop of stack checks.
97 7. I had to make a bunch of changes so that all the built-in file
98 constants match my directory structure. I think it's set up so you
99 only have to change the path in one place now (the defvar of
100 *R-HOME-STR* in rclg-load).
102 ** From the file formerly known as src/NOTES
109 "Gets the sexptype of an robj. WARNING: ASSUMES THAT THE TYPE
110 IS STORED IN THE LOW ORDER 5 BITS OF THE SXPINFO-STRUCT, AND THAT
111 IT CAN BE EXTRACTED VIA A 'mod 32' OPERATION! MAY NOT BE PORTABLE."
116 (defvar *r-NA-internal* -2147483648) ;; PLATFORM SPECIFIC HACK!!!
119 3. SBCL-specific hacks
121 rclg-convert:sequence-to-robj is sbcl-specific! Should think about
122 removing rclg-helpers for more portability, if it's fast enough.
124 Consolidate with-gensyms somewhere?
126 We only get r-names and r-dims back at the "toplevel" call to r.
127 Should rnb protect? Don't think we're using poss-sexp for anything...
129 with-r-traps is SBCL specific.
130 Multiprocessing stuff (with mutex) is SBCL specific.
132 In R, memory.c contains allocVector. Looks like it *should* be doable
133 to directly pass vectors around (non-portably, of course).
146 * Comparison of Implementation and Design of RCLG, CLSR.
148 ** Tools to initialize R
150 1. rclg-init : start-rclg update-R
151 start-rclg-update-thread stop-rclg-update-thread
152 with-R-traps with-r-mutex
154 initialize and maintain the R evaluator process.
156 2. rclg-load : load-r-libraries (FFI initializer, not FFI <-> CL specifier.
158 initialize environment and load libraries.
160 3. clsr-loader: uffi-load-r-library (package: clsr)
162 4. clsr : instantiates an R process.
164 ** Tools to handle R data structures and SEXPs in CL
166 1. rclg-access : r-setcar, r-car, r-cdr
167 (R SEXP content <-> CL data)
169 low-level defuns for data transport between R SEXPs and CL.
171 2. rclg-convert : convert-to-r, convert-from-r, *r-na*, r-nil, r-bound
172 (data type and data conversion)
174 3. rclg-types : SEXP data structure information. exports types, print method.
176 structures and objects for R internal types
178 4. clsr-rref : High level R SEXP data structures and mappings
180 5. clsr-sxp : SEXP data structures and mappings
182 ** Mappings: Name (Function/variable), object registry
184 1. rclg-control : r (internal: rname-to-robj, rname-to-rfun
186 primary interface to R evaluator
188 2. clsr-objects : tracks created R objects in CL (reference counter).
193 1. rclg-control : r (converts results),
194 rnb (uneval'd R object, unprotected)
196 1. rclg-parse-objects : tools to handle string commands.
201 1. rclg-foreigns : maps libR to CL
203 ** CL tools (some R, some general)
205 1. rclg-utils : with-gensyms, over-column-major-indices, to-list, to-vector