/[slime]/slime/swank-backend.lisp
ViewVC logotype

Contents of /slime/swank-backend.lisp

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.97 - (hide annotations)
Wed Mar 22 16:40:01 2006 UTC (8 years, 1 month ago) by dcrosher
Branch: MAIN
CVS Tags: SLIME-1-3
Branch point for: fsm
Changes since 1.96: +7 -1 lines
* Improve the robustness of connection establishment.
1 lgorrie 1.85 ;;; -*- Mode: lisp; indent-tabs-mode: nil; outline-regexp: ";;;;;*" -*-
2 lgorrie 1.1 ;;;
3 lgorrie 1.13 ;;; slime-backend.lisp --- SLIME backend interface.
4 lgorrie 1.1 ;;;
5 lgorrie 1.13 ;;; Created by James Bielman in 2003. Released into the public domain.
6 lgorrie 1.85 ;;;
7     ;;;; Frontmatter
8 lgorrie 1.1 ;;;
9 lgorrie 1.13 ;;; This file defines the functions that must be implemented
10     ;;; separately for each Lisp. Each is declared as a generic function
11     ;;; for which swank-<implementation>.lisp provides methods.
12 lgorrie 1.1
13 heller 1.36 (defpackage :swank-backend
14 lgorrie 1.1 (:use :common-lisp)
15 heller 1.36 (:export #:sldb-condition
16     #:original-condition
17     #:compiler-condition
18     #:message
19     #:short-message
20     #:condition
21     #:severity
22     #:location
23     #:location-p
24     #:location-buffer
25     #:location-position
26     #:position-p
27     #:position-pos
28     #:print-output-to-string
29 mbaringer 1.42 #:quit-lisp
30 crhodes 1.62 #:references
31 mbaringer 1.67 #:unbound-slot-filler
32     ;; inspector related symbols
33     #:inspector
34     #:inspect-for-emacs
35     #:raw-inspection
36     #:fancy-inspection
37 heller 1.70 #:label-value-line
38     #:label-value-line*
39 mbaringer 1.67 ))
40 lgorrie 1.1
41 mbaringer 1.65 (defpackage :swank-mop
42     (:use)
43     (:export
44     ;; classes
45     #:standard-generic-function
46     #:standard-slot-definition
47     #:standard-method
48     #:standard-class
49 mbaringer 1.68 #:eql-specializer
50     #:eql-specializer-object
51 mbaringer 1.65 ;; standard-class readers
52     #:class-default-initargs
53     #:class-direct-default-initargs
54     #:class-direct-slots
55     #:class-direct-subclasses
56     #:class-direct-superclasses
57     #:class-finalized-p
58     #:class-name
59     #:class-precedence-list
60     #:class-prototype
61     #:class-slots
62 mbaringer 1.68 #:specializer-direct-methods
63 mbaringer 1.65 ;; generic function readers
64     #:generic-function-argument-precedence-order
65     #:generic-function-declarations
66     #:generic-function-lambda-list
67     #:generic-function-methods
68     #:generic-function-method-class
69     #:generic-function-method-combination
70     #:generic-function-name
71     ;; method readers
72     #:method-generic-function
73     #:method-function
74     #:method-lambda-list
75     #:method-specializers
76     #:method-qualifiers
77     ;; slot readers
78     #:slot-definition-allocation
79     #:slot-definition-documentation
80     #:slot-definition-initargs
81     #:slot-definition-initform
82     #:slot-definition-initfunction
83     #:slot-definition-name
84     #:slot-definition-type
85     #:slot-definition-readers
86 lgorrie 1.79 #:slot-definition-writers
87 heller 1.95 #:slot-boundp-using-class
88     #:slot-value-using-class
89 lgorrie 1.79 ;; generic function protocol
90 lgorrie 1.82 #:compute-applicable-methods-using-classes
91     #:finalize-inheritance))
92 mbaringer 1.65
93 heller 1.36 (in-package :swank-backend)
94 lgorrie 1.1
95    
96 lgorrie 1.21 ;;;; Metacode
97    
98     (defparameter *interface-functions* '()
99     "The names of all interface functions.")
100    
101     (defparameter *unimplemented-interfaces* '()
102     "List of interface functions that are not implemented.
103     DEFINTERFACE adds to this list and DEFIMPLEMENTATION removes.")
104    
105 heller 1.52 (defmacro definterface (name args documentation &rest default-body)
106 lgorrie 1.21 "Define an interface function for the backend to implement.
107     A generic function is defined with NAME, ARGS, and DOCUMENTATION.
108    
109     If a DEFAULT-BODY is supplied then NO-APPLICABLE-METHOD is specialized
110     to execute the body if the backend doesn't provide a specific
111     implementation.
112    
113     Backends implement these functions using DEFIMPLEMENTATION."
114 lgorrie 1.43 (check-type documentation string "a documentation string")
115 lgorrie 1.21 (flet ((gen-default-impl ()
116 mbaringer 1.73 `(defmethod ,name ,args ,@default-body)))
117 heller 1.76 `(progn (defgeneric ,name ,args (:documentation ,documentation))
118     (pushnew ',name *interface-functions*)
119     ,(if (null default-body)
120     `(pushnew ',name *unimplemented-interfaces*)
121     (gen-default-impl))
122     ;; see <http://www.franz.com/support/documentation/6.2/doc/pages/variables/compiler/s_cltl1-compile-file-toplevel-compatibility-p_s.htm>
123     (eval-when (:compile-toplevel :load-toplevel :execute)
124     (export ',name :swank-backend))
125     ',name)))
126 lgorrie 1.21
127     (defmacro defimplementation (name args &body body)
128 heller 1.25 `(progn (defmethod ,name ,args ,@body)
129     (if (member ',name *interface-functions*)
130     (setq *unimplemented-interfaces*
131     (remove ',name *unimplemented-interfaces*))
132     (warn "DEFIMPLEMENTATION of undefined interface (~S)" ',name))
133     ',name))
134 lgorrie 1.21
135     (defun warn-unimplemented-interfaces ()
136     "Warn the user about unimplemented backend features.
137     The portable code calls this function at startup."
138     (warn "These Swank interfaces are unimplemented:~% ~A"
139     (sort (copy-list *unimplemented-interfaces*) #'string<)))
140    
141 heller 1.69 (defun import-to-swank-mop (symbol-list)
142     (dolist (sym symbol-list)
143     (let* ((swank-mop-sym (find-symbol (symbol-name sym) :swank-mop)))
144     (when swank-mop-sym
145     (unintern swank-mop-sym :swank-mop))
146     (import sym :swank-mop)
147     (export sym :swank-mop))))
148    
149     (defun import-swank-mop-symbols (package except)
150     "Import the mop symbols from PACKAGE to SWANK-MOP.
151     EXCEPT is a list of symbol names which should be ignored."
152     (do-symbols (s :swank-mop)
153     (unless (member s except :test #'string=)
154     (let ((real-symbol (find-symbol (string s) package)))
155 heller 1.76 (assert real-symbol () "Symbol ~A not found in package ~A" s package)
156 heller 1.69 (unintern s :swank-mop)
157     (import real-symbol :swank-mop)
158     (export real-symbol :swank-mop)))))
159    
160 heller 1.88 (defvar *gray-stream-symbols*
161     '(:fundamental-character-output-stream
162     :stream-write-char
163     :stream-fresh-line
164     :stream-force-output
165     :stream-finish-output
166     :fundamental-character-input-stream
167     :stream-read-char
168     :stream-listen
169     :stream-unread-char
170     :stream-clear-input
171     :stream-line-column
172 jsnellman 1.90 :stream-read-char-no-hang
173     ;; STREAM-LINE-LENGTH is an extension to gray streams that's apparently
174 dcrosher 1.91 ;; supported by CMUCL, OpenMCL, SBCL and SCL.
175     #+(or cmu openmcl sbcl scl)
176 jsnellman 1.90 :stream-line-length))
177 heller 1.88
178     (defun import-from (package symbol-names &optional (to-package *package*))
179     "Import the list of SYMBOL-NAMES found in the package PACKAGE."
180     (dolist (name symbol-names)
181     (multiple-value-bind (symbol found) (find-symbol (string name) package)
182     (assert found () "Symbol ~A not found in package ~A" name package)
183     (import symbol to-package))))
184    
185 lgorrie 1.21
186 heller 1.46 ;;;; Utilities
187    
188     (defmacro with-struct ((conc-name &rest names) obj &body body)
189     "Like with-slots but works only for structs."
190     (flet ((reader (slot) (intern (concatenate 'string
191     (symbol-name conc-name)
192     (symbol-name slot))
193     (symbol-package conc-name))))
194     (let ((tmp (gensym "OO-")))
195     ` (let ((,tmp ,obj))
196     (symbol-macrolet
197     ,(loop for name in names collect
198     (typecase name
199     (symbol `(,name (,(reader name) ,tmp)))
200     (cons `(,(first name) (,(reader (second name)) ,tmp)))
201     (t (error "Malformed syntax in WITH-STRUCT: ~A" name))))
202     ,@body)))))
203 lgorrie 1.54
204    
205 lgorrie 1.13 ;;;; TCP server
206    
207 heller 1.29 (definterface create-socket (host port)
208     "Create a listening TCP socket on interface HOST and port PORT .")
209 lgorrie 1.13
210 lgorrie 1.21 (definterface local-port (socket)
211     "Return the local port number of SOCKET.")
212 lgorrie 1.1
213 lgorrie 1.21 (definterface close-socket (socket)
214     "Close the socket SOCKET.")
215 lgorrie 1.1
216 heller 1.93 (definterface accept-connection (socket &key external-format
217 dcrosher 1.97 buffering timeout)
218 heller 1.93 "Accept a client connection on the listening socket SOCKET.
219     Return a stream for the new connection.")
220 heller 1.16
221 heller 1.31 (definterface add-sigio-handler (socket fn)
222 lgorrie 1.21 "Call FN whenever SOCKET is readable.")
223 heller 1.16
224 heller 1.31 (definterface remove-sigio-handlers (socket)
225     "Remove all sigio handlers for SOCKET.")
226    
227     (definterface add-fd-handler (socket fn)
228     "Call FN when Lisp is waiting for input and SOCKET is readable.")
229    
230     (definterface remove-fd-handlers (socket)
231     "Remove all fd-handlers for SOCKET.")
232 heller 1.18
233 heller 1.36 (definterface preferred-communication-style ()
234     "Return one of the symbols :spawn, :sigio, :fd-handler, or NIL."
235     nil)
236    
237 dcrosher 1.97 (definterface set-stream-timeout (stream timeout)
238     "Set the 'stream 'timeout. The timeout is either the real number
239     specifying the timeout in seconds or 'nil for no timeout."
240     (declare (ignore stream timeout))
241     nil)
242    
243 lgorrie 1.13 ;;; Base condition for networking errors.
244 msimmons 1.50 (define-condition network-error (simple-error) ())
245 lgorrie 1.13
246 heller 1.74 (definterface emacs-connected ()
247 lgorrie 1.13 "Hook called when the first connection from Emacs is established.
248     Called from the INIT-FN of the socket server that accepts the
249     connection.
250 lgorrie 1.1
251 lgorrie 1.13 This is intended for setting up extra context, e.g. to discover
252 heller 1.74 that the calling thread is the one that interacts with Emacs."
253 mbaringer 1.73 nil)
254 lgorrie 1.1
255    
256 heller 1.20 ;;;; Unix signals
257    
258     (defconstant +sigint+ 2)
259    
260 heller 1.36 (definterface call-without-interrupts (fn)
261     "Call FN in a context where interrupts are disabled."
262     (funcall fn))
263 heller 1.20
264 heller 1.32 (definterface getpid ()
265     "Return the (Unix) process ID of this superior Lisp.")
266    
267     (definterface lisp-implementation-type-name ()
268     "Return a short name for the Lisp implementation."
269     (lisp-implementation-type))
270 heller 1.20
271 heller 1.51 (definterface default-directory ()
272     "Return the default directory."
273     (directory-namestring (truename *default-pathname-defaults*)))
274    
275 heller 1.39 (definterface set-default-directory (directory)
276     "Set the default directory.
277     This is used to resolve filenames without directory component."
278     (setf *default-pathname-defaults* (truename (merge-pathnames directory)))
279 heller 1.51 (default-directory))
280    
281     (definterface call-with-syntax-hooks (fn)
282     "Call FN with hooks to handle special syntax."
283     (funcall fn))
284 heller 1.39
285 heller 1.52 (definterface default-readtable-alist ()
286 heller 1.77 "Return a suitable initial value for SWANK:*READTABLE-ALIST*."
287 heller 1.52 '())
288    
289 heller 1.58 (definterface quit-lisp ()
290     "Exit the current lisp image.")
291    
292 heller 1.20
293 lgorrie 1.1 ;;;; Compilation
294 dbarlow 1.8
295 lgorrie 1.21 (definterface call-with-compilation-hooks (func)
296 lgorrie 1.47 "Call FUNC with hooks to record compiler conditions.")
297 lgorrie 1.13
298 vsedach 1.14 (defmacro with-compilation-hooks ((&rest ignore) &body body)
299 lgorrie 1.47 "Execute BODY as in CALL-WITH-COMPILATION-HOOKS."
300 vsedach 1.14 (declare (ignore ignore))
301 dbarlow 1.8 `(call-with-compilation-hooks (lambda () (progn ,@body))))
302 lgorrie 1.1
303 pseibel 1.64 (definterface swank-compile-string (string &key buffer position directory)
304 lgorrie 1.47 "Compile source from STRING. During compilation, compiler
305 lgorrie 1.1 conditions must be trapped and resignalled as COMPILER-CONDITIONs.
306    
307     If supplied, BUFFER and POSITION specify the source location in Emacs.
308    
309     Additionally, if POSITION is supplied, it must be added to source
310 pseibel 1.64 positions reported in compiler conditions.
311    
312     If DIRECTORY is specified it may be used by certain implementations to
313     rebind *DEFAULT-PATHNAME-DEFAULTS* which may improve the recording of
314     source information.")
315 lgorrie 1.1
316 lgorrie 1.43 (definterface operate-on-system (system-name operation-name &rest keyword-args)
317     "Perform OPERATION-NAME on SYSTEM-NAME using ASDF.
318     The KEYWORD-ARGS are passed on to the operation.
319     Example:
320     \(operate-on-system \"SWANK\" \"COMPILE-OP\" :force t)"
321     (unless (member :asdf *features*)
322     (error "ASDF is not loaded."))
323 heller 1.30 (with-compilation-hooks ()
324 dcrosher 1.96 (let ((operate (find-symbol (symbol-name '#:operate) :asdf))
325 lgorrie 1.43 (operation (find-symbol operation-name :asdf)))
326     (when (null operation)
327     (error "Couldn't find ASDF operation ~S" operation-name))
328     (apply operate operation system-name keyword-args))))
329 mbaringer 1.26
330 heller 1.86 (definterface swank-compile-file (filename load-p &optional external-format)
331 lgorrie 1.1 "Compile FILENAME signalling COMPILE-CONDITIONs.
332 lgorrie 1.21 If LOAD-P is true, load the file after compilation.")
333 lgorrie 1.1
334 heller 1.72 (deftype severity ()
335     '(member :error :read-error :warning :style-warning :note))
336 lgorrie 1.13
337     ;; Base condition type for compiler errors, warnings and notes.
338     (define-condition compiler-condition (condition)
339     ((original-condition
340     ;; The original condition thrown by the compiler if appropriate.
341     ;; May be NIL if a compiler does not report using conditions.
342     :type (or null condition)
343     :initarg :original-condition
344     :accessor original-condition)
345    
346     (severity :type severity
347     :initarg :severity
348     :accessor severity)
349    
350     (message :initarg :message
351     :accessor message)
352    
353 heller 1.30 (short-message :initarg :short-message
354     :initform nil
355     :accessor short-message)
356 crhodes 1.62
357     (references :initarg :references
358     :initform nil
359     :accessor references)
360 heller 1.30
361 lgorrie 1.13 (location :initarg :location
362     :accessor location)))
363 heller 1.30
364 lgorrie 1.17
365 lgorrie 1.13 ;;;; Streams
366    
367 lgorrie 1.21 (definterface make-fn-streams (input-fn output-fn)
368 lgorrie 1.13 "Return character input and output streams backended by functions.
369     When input is needed, INPUT-FN is called with no arguments to
370     return a string.
371     When output is ready, OUTPUT-FN is called with the output as its
372     argument.
373    
374     Output should be forced to OUTPUT-FN before calling INPUT-FN.
375    
376 lgorrie 1.21 The streams are returned as two values.")
377 lgorrie 1.13
378 lgorrie 1.60 (definterface make-stream-interactive (stream)
379     "Do any necessary setup to make STREAM work interactively.
380     This is called for each stream used for interaction with the user
381     \(e.g. *standard-output*). An implementation could setup some
382     implementation-specific functions to control output flushing at the
383     like."
384 mbaringer 1.73 (declare (ignore stream))
385 lgorrie 1.60 nil)
386    
387 lgorrie 1.1
388     ;;;; Documentation
389    
390 heller 1.36 (definterface arglist (name)
391 mbaringer 1.65 "Return the lambda list for the symbol NAME. NAME can also be
392     a lisp function object, on lisps which support this.
393    
394     The result can be a list or the :not-available if the arglist
395     cannot be determined."
396     (declare (ignore name))
397     :not-available)
398 heller 1.36
399 mbaringer 1.65 (definterface function-name (function)
400     "Return the name of the function object FUNCTION.
401    
402     The result is either a symbol, a list, or NIL if no function name is available."
403     (declare (ignore function))
404     nil)
405 lgorrie 1.1
406 lgorrie 1.21 (definterface macroexpand-all (form)
407 lgorrie 1.1 "Recursively expand all macros in FORM.
408 lgorrie 1.21 Return the resulting form.")
409 lgorrie 1.1
410 heller 1.94 (definterface compiler-macroexpand-1 (form &optional env)
411     "Call the compiler-macro for form.
412     If FORM is a function call for which a compiler-macro has been
413     defined, invoke the expander function using *macroexpand-hook* and
414     return the results and T. Otherwise, return the original form and
415     NIL."
416     (let ((fun (and (consp form) (compiler-macro-function (car form)))))
417     (if fun
418     (let ((result (funcall *macroexpand-hook* fun form env)))
419     (values result (not (eq result form))))
420     (values form nil))))
421    
422     (definterface compiler-macroexpand (form &optional env)
423     "Repetitively call `compiler-macroexpand-1'."
424     (labels ((frob (form expanded)
425     (multiple-value-bind (new-form newly-expanded)
426     (compiler-macroexpand-1 form env)
427     (if newly-expanded
428     (frob new-form t)
429     (values new-form expanded)))))
430     (frob form env)))
431    
432 lgorrie 1.21 (definterface describe-symbol-for-emacs (symbol)
433 lgorrie 1.1 "Return a property list describing SYMBOL.
434    
435     The property list has an entry for each interesting aspect of the
436     symbol. The recognised keys are:
437    
438 heller 1.86 :VARIABLE :FUNCTION :SETF :SPECIAL-OPERATOR :MACRO :COMPILER-MACRO
439     :TYPE :CLASS :ALIEN-TYPE :ALIEN-STRUCT :ALIEN-UNION :ALIEN-ENUM
440 lgorrie 1.1
441     The value of each property is the corresponding documentation string,
442 heller 1.86 or :NOT-DOCUMENTED. It is legal to include keys not listed here (but
443     slime-print-apropos in Emacs must know about them).
444 lgorrie 1.1
445     Properties should be included if and only if they are applicable to
446     the symbol. For example, only (and all) fbound symbols should include
447     the :FUNCTION property.
448    
449     Example:
450     \(describe-symbol-for-emacs 'vector)
451     => (:CLASS :NOT-DOCUMENTED
452     :TYPE :NOT-DOCUMENTED
453 lgorrie 1.21 :FUNCTION \"Constructs a simple-vector from the given objects.\")")
454    
455     (definterface describe-definition (name type)
456     "Describe the definition NAME of TYPE.
457     TYPE can be any value returned by DESCRIBE-SYMBOL-FOR-EMACS.
458    
459     Return a documentation string, or NIL if none is available.")
460 lgorrie 1.2
461    
462     ;;;; Debugging
463    
464 heller 1.92 (definterface install-debugger-globally (function)
465     "Install FUNCTION as the debugger for all threads/processes. This
466     usually involves setting *DEBUGGER-HOOK* and, if the implementation
467     permits, hooking into BREAK as well."
468     (setq *debugger-hook* function))
469    
470 lgorrie 1.21 (definterface call-with-debugging-environment (debugger-loop-fn)
471 lgorrie 1.2 "Call DEBUGGER-LOOP-FN in a suitable debugging environment.
472    
473     This function is called recursively at each debug level to invoke the
474     debugger loop. The purpose is to setup any necessary environment for
475     other debugger callbacks that will be called within the debugger loop.
476    
477     For example, this is a reasonable place to compute a backtrace, switch
478 lgorrie 1.21 to safe reader/printer settings, and so on.")
479 lgorrie 1.2
480 heller 1.80 (definterface call-with-debugger-hook (hook fun)
481     "Call FUN and use HOOK as debugger hook.
482    
483     HOOK should be called for both BREAK and INVOKE-DEBUGGER."
484     (let ((*debugger-hook* hook))
485     (funcall fun)))
486    
487 lgorrie 1.2 (define-condition sldb-condition (condition)
488     ((original-condition
489     :initarg :original-condition
490 heller 1.5 :accessor original-condition))
491 heller 1.63 (:report (lambda (condition stream)
492     (format stream "Condition in debugger code~@[: ~A~]"
493     (original-condition condition))))
494 lgorrie 1.2 (:documentation
495     "Wrapper for conditions that should not be debugged.
496    
497     When a condition arises from the internals of the debugger, it is not
498     desirable to debug it -- we'd risk entering an endless loop trying to
499     debug the debugger! Instead, such conditions can be reported to the
500     user without (re)entering the debugger by wrapping them as
501     `sldb-condition's."))
502    
503 heller 1.36 (definterface compute-backtrace (start end)
504 lgorrie 1.3 "Return a list containing a backtrace of the condition current
505     being debugged. The results are unspecified if this function is
506 heller 1.36 called outside the dynamic contour CALL-WITH-DEBUGGING-ENVIRONMENT.
507    
508     START and END are zero-based indices constraining the number of frames
509     returned. Frame zero is defined as the frame which invoked the
510     debugger. If END is nil, return the frames from START to the end of
511     the stack.")
512 lgorrie 1.3
513 heller 1.36 (definterface print-frame (frame stream)
514     "Print frame to stream.")
515 heller 1.70
516 lgorrie 1.21 (definterface frame-source-location-for-emacs (frame-number)
517     "Return the source location for FRAME-NUMBER.")
518 lgorrie 1.3
519 lgorrie 1.21 (definterface frame-catch-tags (frame-number)
520 lgorrie 1.3 "Return a list of XXX list of what? catch tags for a debugger
521     stack frame. The results are undefined unless this is called
522     within the dynamic contour of a function defined by
523 lgorrie 1.21 DEFINE-DEBUGGER-HOOK.")
524 lgorrie 1.3
525 lgorrie 1.21 (definterface frame-locals (frame-number)
526 heller 1.57 "Return a list of XXX local variable designators define me
527 lgorrie 1.3 for a debugger stack frame. The results are undefined unless
528     this is called within the dynamic contour of a function defined
529 lgorrie 1.21 by DEFINE-DEBUGGER-HOOK.")
530 heller 1.37
531 heller 1.57 (definterface frame-var-value (frame var)
532     "Return the value of VAR in FRAME.
533     FRAME is the number of the frame in the backtrace.
534     VAR is the number of the variable in the frame.")
535    
536 heller 1.37 (definterface disassemble-frame (frame-number)
537     "Disassemble the code for the FRAME-NUMBER.
538     The output should be written to standard output.
539 heller 1.84 FRAME-NUMBER is a non-negative integer.")
540 heller 1.37
541 lgorrie 1.21 (definterface eval-in-frame (form frame-number)
542 lgorrie 1.3 "Evaluate a Lisp form in the lexical context of a stack frame
543     in the debugger. The results are undefined unless called in the
544     dynamic contour of a function defined by DEFINE-DEBUGGER-HOOK.
545    
546     FRAME-NUMBER must be a positive integer with 0 indicating the
547     frame which invoked the debugger.
548    
549     The return value is the result of evaulating FORM in the
550 lgorrie 1.21 appropriate context.")
551 heller 1.22
552     (definterface return-from-frame (frame-number form)
553     "Unwind the stack to the frame FRAME-NUMBER and return the value(s)
554     produced by evaluating FORM in the frame context to its caller.
555    
556     Execute any clean-up code from unwind-protect forms above the frame
557     during unwinding.
558    
559     Return a string describing the error if it's not possible to return
560     from the frame.")
561    
562     (definterface restart-frame (frame-number)
563     "Restart execution of the frame FRAME-NUMBER with the same arguments
564     as it was called originally.")
565 lgorrie 1.3
566 lgorrie 1.49 (definterface format-sldb-condition (condition)
567     "Format a condition for display in SLDB."
568     (princ-to-string condition))
569    
570     (definterface condition-references (condition)
571     "Return a list of documentation references for a condition.
572     Each reference is one of:
573     (:ANSI-CL
574     {:FUNCTION | :SPECIAL-OPERATOR | :MACRO | :SECTION | :GLOSSARY }
575     symbol-or-name)
576     (:SBCL :NODE node-name)"
577 mbaringer 1.73 (declare (ignore condition))
578 lgorrie 1.49 '())
579 heller 1.52
580 heller 1.69 (definterface condition-extras (condition)
581     "Return a list of extra for the debugger.
582     The allowed elements are of the form:
583     (:SHOW-FRAME-SOURCE frame-number)"
584 mbaringer 1.73 (declare (ignore condition))
585 heller 1.69 '())
586    
587 heller 1.71 (definterface activate-stepping (frame-number)
588     "Prepare the frame FRAME-NUMBER for stepping.")
589 heller 1.69
590     (definterface sldb-break-on-return (frame-number)
591     "Set a breakpoint in the frame FRAME-NUMBER.")
592    
593     (definterface sldb-break-at-start (symbol)
594     "Set a breakpoint on the beginning of the function for SYMBOL.")
595 heller 1.52
596 lgorrie 1.49
597 lgorrie 1.3
598 heller 1.36 ;;;; Definition finding
599    
600     (defstruct (:location (:type list) :named
601 lgorrie 1.45 (:constructor make-location
602     (buffer position &optional hints)))
603     buffer position
604     ;; Hints is a property list optionally containing:
605     ;; :snippet SOURCE-TEXT
606     ;; This is a snippet of the actual source text at the start of
607     ;; the definition, which could be used in a text search.
608     hints)
609 heller 1.36
610     (defstruct (:error (:type list) :named (:constructor)) message)
611     (defstruct (:file (:type list) :named (:constructor)) name)
612     (defstruct (:buffer (:type list) :named (:constructor)) name)
613     (defstruct (:position (:type list) :named (:constructor)) pos)
614    
615     (definterface find-definitions (name)
616     "Return a list ((DSPEC LOCATION) ...) for NAME's definitions.
617    
618 heller 1.38 NAME is a \"definition specifier\".
619 heller 1.36
620 heller 1.38 DSPEC is a \"definition specifier\" describing the
621 heller 1.36 definition, e.g., FOO or (METHOD FOO (STRING NUMBER)) or
622 heller 1.38 \(DEFVAR FOO).
623    
624     LOCATION is the source location for the definition.")
625 heller 1.36
626 lgorrie 1.61 (definterface buffer-first-change (filename)
627     "Called for effect the first time FILENAME's buffer is modified."
628 mbaringer 1.73 (declare (ignore filename))
629 lgorrie 1.61 nil)
630    
631 heller 1.36
632     ;;;; XREF
633    
634     (definterface who-calls (function-name)
635     "Return the call sites of FUNCTION-NAME (a symbol).
636     The results is a list ((DSPEC LOCATION) ...).")
637    
638 heller 1.81 (definterface calls-who (function-name)
639     "Return the call sites of FUNCTION-NAME (a symbol).
640     The results is a list ((DSPEC LOCATION) ...).")
641    
642 heller 1.36 (definterface who-references (variable-name)
643     "Return the locations where VARIABLE-NAME (a symbol) is referenced.
644     See WHO-CALLS for a description of the return value.")
645    
646     (definterface who-binds (variable-name)
647     "Return the locations where VARIABLE-NAME (a symbol) is bound.
648     See WHO-CALLS for a description of the return value.")
649    
650     (definterface who-sets (variable-name)
651     "Return the locations where VARIABLE-NAME (a symbol) is set.
652     See WHO-CALLS for a description of the return value.")
653    
654     (definterface who-macroexpands (macro-name)
655     "Return the locations where MACRO-NAME (a symbol) is expanded.
656     See WHO-CALLS for a description of the return value.")
657    
658     (definterface who-specializes (class-name)
659     "Return the locations where CLASS-NAME (a symbol) is specialized.
660     See WHO-CALLS for a description of the return value.")
661    
662     ;;; Simpler variants.
663    
664     (definterface list-callers (function-name)
665     "List the callers of FUNCTION-NAME.
666     This function is like WHO-CALLS except that it is expected to use
667     lower-level means. Whereas WHO-CALLS is usually implemented with
668     special compiler support, LIST-CALLERS is usually implemented by
669     groveling for constants in function objects throughout the heap.
670    
671     The return value is as for WHO-CALLS.")
672    
673     (definterface list-callees (function-name)
674     "List the functions called by FUNCTION-NAME.
675     See LIST-CALLERS for a description of the return value.")
676    
677    
678 heller 1.23 ;;;; Profiling
679    
680     ;;; The following functions define a minimal profiling interface.
681    
682     (definterface profile (fname)
683     "Marks symbol FNAME for profiling.")
684    
685     (definterface profiled-functions ()
686     "Returns a list of profiled functions.")
687    
688     (definterface unprofile (fname)
689     "Marks symbol FNAME as not profiled.")
690    
691     (definterface unprofile-all ()
692     "Marks all currently profiled functions as not profiled."
693     (dolist (f (profiled-functions))
694     (unprofile f)))
695    
696     (definterface profile-report ()
697     "Prints profile report.")
698    
699     (definterface profile-reset ()
700     "Resets profile counters.")
701    
702     (definterface profile-package (package callers-p methods)
703     "Wrap profiling code around all functions in PACKAGE. If a function
704     is already profiled, then unprofile and reprofile (useful to notice
705     function redefinition.)
706    
707     If CALLERS-P is T names have counts of the most common calling
708     functions recorded.
709    
710     When called with arguments :METHODS T, profile all methods of all
711     generic functions having names in the given package. Generic functions
712     themselves, that is, their dispatch functions, are left alone.")
713    
714    
715 heller 1.19 ;;;; Inspector
716 lgorrie 1.56
717 mbaringer 1.67 (defclass inspector ()
718     ()
719     (:documentation "Super class of inspector objects.
720    
721     Implementations should sub class in order to dispatch off of the
722     inspect-for-emacs method."))
723    
724     (definterface make-default-inspector ()
725     "Return an inspector object suitable for passing to inspect-for-emacs.")
726    
727     (definterface inspect-for-emacs (object inspector)
728 heller 1.86 "Explain to Emacs how to inspect OBJECT.
729 mbaringer 1.67
730     The argument INSPECTOR is an object representing how to get at
731     the internals of OBJECT, it is usually an implementation specific
732     class used simply for dispatching to the proper method.
733    
734     The orgument INSPECTION-MODE is an object specifying how, and
735     what, to show to the user.
736    
737     Returns two values: a string which will be used as the title of
738     the inspector buffer and a list specifying how to render the
739     object for inspection.
740    
741 lgorrie 1.83 Every element of the list must be either a string, which will be
742 mbaringer 1.67 inserted into the buffer as is, or a list of the form:
743    
744     (:value object &optional format) - Render an inspectable
745     object. If format is provided it must be a string and will be
746     rendered in place of the value, otherwise use princ-to-string.
747    
748     (:newline) - Render a \\n
749    
750     (:action label lambda) - Render LABEL (a text string) which when
751     clicked will call LAMBDA.
752    
753     NIL - do nothing.")
754    
755 mbaringer 1.73 (defmethod inspect-for-emacs ((object t) (inspector t))
756 mbaringer 1.67 "Generic method for inspecting any kind of object.
757    
758     Since we don't know how to deal with OBJECT we simply dump the
759     output of CL:DESCRIBE."
760 mbaringer 1.73 (declare (ignore inspector))
761 heller 1.86 (values
762     "A value."
763     `("Type: " (:value ,(type-of object)) (:newline)
764     "Don't know how to inspect the object, dumping output of CL:DESCRIBE:"
765     (:newline) (:newline)
766     ,(with-output-to-string (desc) (describe object desc)))))
767 heller 1.70
768 heller 1.84 ;;; Utilities for inspector methods.
769 heller 1.70 ;;;
770     (defun label-value-line (label value)
771     "Create a control list which prints \"LABEL: VALUE\" in the inspector."
772     (list (princ-to-string label) ": " `(:value ,value) '(:newline)))
773    
774     (defmacro label-value-line* (&rest label-values)
775     ` (append ,@(loop for (label value) in label-values
776     collect `(label-value-line ,label ,value))))
777 heller 1.19
778 heller 1.29 (definterface describe-primitive-type (object)
779 heller 1.35 "Return a string describing the primitive type of object."
780 heller 1.36 (declare (ignore object))
781 heller 1.35 "N/A")
782 heller 1.19
783    
784 heller 1.36 ;;;; Multithreading
785 lgorrie 1.21 ;;;
786     ;;; The default implementations are sufficient for non-multiprocessing
787     ;;; implementations.
788 lgorrie 1.9
789 heller 1.89 (definterface initialize-multiprocessing ()
790     "Initialize multiprocessing, if necessary."
791     nil)
792 lgorrie 1.9
793 heller 1.89 (definterface startup-idle-and-top-level-loops ()
794     "This function is called directly through the listener, not in an RPC
795 lgorrie 1.9 from Emacs. This is to support interfaces such as CMUCL's
796     MP::STARTUP-IDLE-AND-TOP-LEVEL-LOOPS which does not return like a
797 lgorrie 1.21 normal function."
798     nil)
799 lgorrie 1.9
800 lgorrie 1.21 (definterface spawn (fn &key name)
801     "Create a new thread to call FN.")
802 lgorrie 1.17
803 heller 1.58 (definterface thread-id (thread)
804     "Return an Emacs-parsable object to identify THREAD.
805    
806     Ids should be comparable with equal, i.e.:
807     (equal (thread-id <t1>) (thread-id <t2>)) <==> (eq <t1> <t2>)")
808    
809     (definterface find-thread (id)
810     "Return the thread for ID.
811     ID should be an id previously obtained with THREAD-ID.
812     Can return nil if the thread no longer exists.")
813    
814 heller 1.28 (definterface thread-name (thread)
815     "Return the name of THREAD.
816 lgorrie 1.9
817     Thread names are be single-line strings and are meaningful to the
818 lgorrie 1.21 user. They do not have to be unique."
819 heller 1.28 (declare (ignore thread))
820 lgorrie 1.21 "The One True Thread")
821 lgorrie 1.9
822 heller 1.28 (definterface thread-status (thread)
823     "Return a string describing THREAD's state."
824     (declare (ignore thread))
825     "")
826    
827 lgorrie 1.21 (definterface make-lock (&key name)
828 lgorrie 1.17 "Make a lock for thread synchronization.
829 lgorrie 1.21 Only one thread may hold the lock (via CALL-WITH-LOCK-HELD) at a time."
830 heller 1.23 (declare (ignore name))
831 lgorrie 1.21 :null-lock)
832 lgorrie 1.9
833 lgorrie 1.21 (definterface call-with-lock-held (lock function)
834     "Call FUNCTION with LOCK held, queueing if necessary."
835 heller 1.24 (declare (ignore lock)
836     (type function function))
837 lgorrie 1.21 (funcall function))
838 heller 1.25
839     (definterface current-thread ()
840     "Return the currently executing thread."
841     0)
842 heller 1.28
843     (definterface all-threads ()
844     "Return a list of all threads.")
845    
846     (definterface thread-alive-p (thread)
847 heller 1.35 "Test if THREAD is termintated."
848     (member thread (all-threads)))
849 heller 1.25
850     (definterface interrupt-thread (thread fn)
851     "Cause THREAD to execute FN.")
852    
853 mbaringer 1.34 (definterface kill-thread (thread)
854     "Kill THREAD."
855     (declare (ignore thread))
856     nil)
857    
858 heller 1.25 (definterface send (thread object)
859     "Send OBJECT to thread THREAD.")
860    
861     (definterface receive ()
862 heller 1.84 "Return the next message from current thread's mailbox.")
863 mbaringer 1.78
864 heller 1.81 (definterface toggle-trace (spec)
865     "Toggle tracing of the function(s) given with SPEC.
866     SPEC can be:
867     (setf NAME) ; a setf function
868     (:defmethod NAME QUALIFIER... (SPECIALIZER...)) ; a specific method
869     (:defgeneric NAME) ; a generic function with all methods
870     (:call CALLER CALLEE) ; trace calls from CALLER to CALLEE.
871     (:labels TOPLEVEL LOCAL)
872     (:flet TOPLEVEL LOCAL) ")
873 mkoeppe 1.87
874    
875     ;;;; Weak datastructures
876    
877     (definterface make-weak-key-hash-table (&rest args)
878     "Like MAKE-HASH-TABLE, but weak w.r.t. the keys."
879     (apply #'make-hash-table args))
880    
881     (definterface make-weak-value-hash-table (&rest args)
882     "Like MAKE-HASH-TABLE, but weak w.r.t. the values."
883     (apply #'make-hash-table args))

  ViewVC Help
Powered by ViewVC 1.1.5