| blob | 16eac505467a64b49de905cbed42e27667b5c34c |
1 ;;; -*- Mode: Lisp; Package: Maxima; Syntax: Common-Lisp; Base: 10 -*- ;;;;
2 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3 ;;; The data in this file contains enhancments. ;;;;;
4 ;;; ;;;;;
5 ;;; Copyright (c) 1984,1987 by William Schelter,University of Texas ;;;;;
6 ;;; All rights reserved ;;;;;
7 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
8 ;;; (c) Copyright 1981 Massachusetts Institute of Technology ;;;
9 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
17 ;;; a reasonable trace capability for macsyma users.
18 ;;; 8:10pm Saturday, 10 January 1981 -GJC.
20 ;; TRACE(F1,F2,...) /* traces the functions */
21 ;; TRACE() /* returns a list of functions under trace */
22 ;; UNTRACE(F1,F2,...) /* untraces the functions */
23 ;; UNTRACE() /* untraces all functions. */
24 ;; TRACE_MAX_INDENT /* The maximum indentation of trace printing. */
25 ;;
26 ;; TRACE_OPTIONS(F,option1,option2,...) /* gives F options */
27 ;;
28 ;; TRACE_BREAK_ARG /* Bound to list of argument during BREAK ENTER,
29 ;; and the return value during BREAK EXIT.
30 ;; This lets you change the arguments to a function,
31 ;; or make a function return a different value,
32 ;; which are both useful debugging hacks.
33 ;;
34 ;; You probably want to give this a short alias
35 ;; for typing convenience.
36 ;; */
37 ;;
38 ;; An option is either a keyword, FOO.
39 ;; or an expression FOO(PREDICATE_FUNCTION);
40 ;;
41 ;; A keyword means that the option is in effect, an keyword
42 ;; expression means to apply the predicate function to some arguments
43 ;; to determine if the option is in effect. The argument list is always
44 ;; [LEVEL,DIRECTION, FUNCTION, ITEM] where
45 ;; LEVEL is the recursion level for the function.
46 ;; DIRECTION is either ENTER or EXIT.
47 ;; FUNCTION is the name of the function.
48 ;; ITEM is either the argument list or the return value.
49 ;;
50 ;; ----------------------------------------------
51 ;; | Keyword | Meaning of return value |
52 ;; ----------------------------------------------
53 ;; | NOPRINT | If TRUE do no printing. |
54 ;; | BREAK | If TRUE give a breakpoint. |
55 ;; | LISP_PRINT | If TRUE use lisp printing. |
56 ;; | INFO | Extra info to print |
57 ;; | ERRORCATCH | If TRUE errors are caught. |
58 ;; ----------------------------------------------
59 ;;
60 ;; General interface functions. These would be called by user debugging utilities.
61 ;;
62 ;; TRACE_IT('F) /* Trace the function named F */
63 ;; TRACE /* list of functions presently traced. */
64 ;; UNTRACE_IT('F) /* Untrace the function named F */
65 ;; GET('F,'TRACE_OPTIONS) /* Access the trace options of F */
66 ;;
67 ;; Sophisticated feature:
68 ;; TRACE_SAFETY a variable with default value TRUE.
69 ;; Example: F(X):=X; BREAKP([L]):=(PRINT("Hi!",L),FALSE),
70 ;; TRACE(F,BREAKP); TRACE_OPTIONS(F,BREAK(BREAKP));
71 ;; F(X); Note that even though BREAKP is traced, and it is called,
72 ;; it does not print out as if it were traced. If you set
73 ;; TRACE_SAFETY:FALSE; then F(X); will cause a normal trace-printing
74 ;; for BREAKP. However, then consider TRACE_OPTIONS(BREAKP,BREAK(BREAKP));
75 ;; When TRACE_SAFETY:FALSE; F(X); will give an infinite recursion,
76 ;; which it would not if safety were turned on.
77 ;; [Just thinking about this gives me a headache.]
79 ;; Internal notes on this package: -jkf
80 ;; Trace works by storing away the real definition of a function and
81 ;; replacing it by a 'shadow' function. The shadow function prints a
82 ;; message, calls the real function, and then prints a message as it
83 ;; leaves. The type of the shadow function may differ from the
84 ;; function being shadowed. The chart below shows what type of shadow
85 ;; function is needed for each type of Macsyma function.
86 ;;
87 ;; Macsyma function shadow type hook type mget
88 ;; ____________________________________________________________
89 ;; subr expr expr
90 ;; expr expr expr
91 ;; lsubr expr expr
92 ;; fsubr fexpr fexpr
93 ;; fexpr fexpr fexpr
94 ;; mexpr expr expr t
95 ;; mfexpr* mfexpr* macro
96 ;; mfexpr*s mfexpr* macro
97 ;;
98 ;; The 'hook type' refers to the form of the shadow function. 'expr' types
99 ;; are really lexprs, they expect any number of evaluated arguments.
100 ;; 'fexpr' types expect one unevaluated argument which is the list of
101 ;; arguments. 'macro' types expect one argument, the caar of which is the
102 ;; name of the function, and the cdr of which is a list of arguments.
103 ;;
104 ;; For systems which store all function properties on the property list,
105 ;; it is easy to shadow a function. For systems with function cells,
106 ;; the situation is a bit more difficult since the standard types of
107 ;; functions are stored in the function cell (expr,fexpr,lexpr), whereas
108 ;; the macsyma functions (mfexpr*,...) are stored on the property list.
109 ;;
111 ;; 1) The variety of maxima functions is much more restricted than
112 ;; what the table above shows. I think the following table gives
113 ;; the correct picture (like its counterpart, it ignores maxima
114 ;; macros or functional arrays).
115 ;;
116 ;;
117 ;; Maxima function shadow type hook type mget
118 ;; ____________________________________________________________
119 ;; expr expr expr
120 ;; mexpr expr expr t
121 ;; mfexpr* mfexpr* expr
122 ;;
123 ;; These types have the following meaning: Suppose MFUN evaluates to some
124 ;; symbol in the MAXIMA package. That this symbol is of type
125 ;;
126 ;; - EXPR (or SUBR) implies that it has a lisp function definition
127 ;; (SYMBOL-FUNCTION MFUN).
128 ;;
129 ;; - MEXPR implies that it has a (parsed) maxima language definition
130 ;; (MGET MFUN 'MEXPR) and all arguments are evaluated by MEVAL.
131 ;;
132 ;; - MFEXPR* implies that it has a lisp function definition
133 ;; (GET MFUN 'MFEXPR*) and its arguments are not automatically
134 ;; evaluated by MEVAL.
135 ;;
136 ;; Note that the shadow type has to agree with the original function's
137 ;; type in the way arguments are evaluated. On the other hand, I think
138 ;; we are left with EXPR as the only hook type; as a matter of fact, this
139 ;; is equivalent to the next point:
140 ;;
141 ;; 2) There is no need for MAKE-TRACE-HOOK to dispatch with respect to
142 ;; HOOK-TYPE since, roughly speaking, proper handling of the traced
143 ;; function's arguments is done by the trace handler in concert with
144 ;; MEVAL*.
145 ;;
146 ;; Note that I also removed the COPY-LIST used to pass the traced
147 ;; function's argument list to the trace handler.
148 ;;
149 ;; There remains an annoying problem with translated functions: tracing
150 ;; some function of type MEXPR and then loading its translated version
151 ;; (which is of type EXPR) will not cleanly untrace it (i.e., it is
152 ;; effectively no longer traced but it remains on the list of traced
153 ;; functions). I think that this has to be fixed somewhere in the
154 ;; translation package. -wj
156 ;; Maxima offers no user-level mechanism for manipulating multiple
157 ;; return values; however, multiple (lisp) return values need to be
158 ;; handled and returned correctly in traced or timed functions.
159 ;; For example, if a user traces or times a rule created by defrule
160 ;; then the second return value must be propagated so apply1 and
161 ;; friends know when the rule hits (the documentation states that
162 ;; these rules can be treated as functions, so it seems reasonable
163 ;; to want to trace or time them).
164 ;;
165 ;; We still pretend like there is only one return value when we
166 ;; print the trace, pass the value to a trace option predicate or
167 ;; allow the user to set a new return value at a breakpoint. This
168 ;; is both for backward-compatibility (particularly in predicates)
169 ;; and because Maxima doesn't actually support multiple values anyway.
171 ;;; Structures.
187 ;;; User interface functions.
192 "totally random utility function"
195 default
201 llist))))))
219 ;;; System interface functions.
223 ;; A list of functions called by the TRACE-HANDLEr at times when
224 ;; it cannot possibly shield itself from a continuation which would
225 ;; cause infinite recursion. We are assuming the best-case of
226 ;; compile code.
234 nil)
236 ;; Things which redefine should be expected to reset this
237 ;; to NIL.
239 nil)
242 nil)
245 nil)
247 (mtell (intl:gettext "trace: ~@:M is a macro, so it won't trace well; try 'macroexpand' to debug it.~%") fun)
248 nil)
255 nil)))
266 nil)
269 nil)
275 ;; yes, he has re-defined or untraced the function
276 ;; during the trace-handling application.
277 ;; This is not strange, in fact it happens all the
278 ;; time when the user is using the $ERRORCATCH option!
299 ;; Placing the TRACE functional hook.
300 ;; Because the function properties in macsyma are used by the EDITOR, SAVE,
301 ;; and GRIND commands it is not possible to simply replace the function
302 ;; being traced with a hook and to store the old definition someplace.
303 ;; [We do know how to cons up machine-code hooks on the fly, so that
304 ;; is not stopping us].
307 ;; This data should be formalized somehow at the time of
308 ;; definition of the DEFining form.
327 ; We're tracing an mexpr with special evaluation rules (mfexpr).
328 ; Let's put a Maxima lambda expression on the plist that calls
329 ; the trace hook. Then in the evaluator we can just have mlambda
330 ; do the work for us.
331 ;
332 ; If there is not a rest argument in the mexpr's lambda list
333 ; then this newly-constructed lambda expression just does a
334 ; funcall. If there is a rest argument then it requires a
335 ; little more work.
344 ; This is the mfexpr+mlexpr case (we have at
345 ; least one quoted arg and a rest arg).
346 ;
347 ; The use of call-hook here is basically like
348 ;
349 ; `(($apply) ,value
350 ; (($append)
351 ; ((mlist) ,@(butlast params))
352 ; ,(car (last params))))
353 ;
354 ; but faster. We just have to construct
355 ; things so simplifya doesn't barf on any
356 ; intermediate expressions.
369 ;; At this point, we know that FUN is traced.
381 ;;--- trace-fsymeval :: find original function
382 ;; fun : a function which is being traced. The original definition may
383 ;; be hidden on the property list behind the shadow function.
384 ;;
400 ;;; The handling of a traced call.
405 ;; is by far the best dynamic binding generally available.
410 ;; We really want to (BINDF (TRACE-LEVEL FUN) (1+ (TRACE-LEVEL FUN)) ...)
411 ;; (Think about PROGV and SETF and BINDF. If the trace object where
412 ;; a closure, then we want to fluid bind instance variables.)
432 ;; We were called by the trace-handler or by $untrace and the function
433 ;; fun is to be untraced.
473 ;; The (Trace-options function) access is not optimized to take place
474 ;; only once per trace-handle call. This is so that the user may change
475 ;; options during his break loops.
476 ;; Question: Should we bind return-to-trace-handle to NIL when we
477 ;; call the user's predicate? He has control over his own lossage.
488 nil)))
504 largs)))
513 " "
543 largs))
550 ; If trace_break_arg is the same (in the sense of eq) now
551 ; as when we started the breakpoint, then return all of the
552 ; original return values from the function. This means if
553 ; the user sets trace_break_arg but its value is eq to its
554 ; original value (which is only the primary return value
555 ; from the original function) then we still return the extra
556 ; values (if there are any). I (kjak) don't think this is
557 ; strictly correct, but we can try to fix it up later if
558 ; anyone ever really cares about this corner case involving
559 ; multiple return values, exit breakpoints and setting
560 ; trace_break_arg to the same value it started with.
562 ret-vals
564 ret-vals))
583 dlist
586 ;; I GUESS ALL OF THE STRINGS IN THIS FUNCTION NEED TO BE GETTEXT'D TOO
587 ;; JUST CAN'T BRING MYSELF TO DO IT
591 "Retry with same arguments?"
592 "Retry with new arguments?"
595 "at level" level
605 "Enter new argument list for"
612 ;;; application dispatch, and the consing up of the trace hook.
622 fun))
623 try)
627 ;; The semantics of $TRANSRUN are herein taken from DESCRIBE,
628 ;; a careful reading of MEVAL1 reveals, well... I've promised to watch
629 ;; my language in these comments.
635 ;; the default, so its really a waste to have looked for
636 ;; those mprops. Its better to fix the crock than to
637 ;; optimize this though!
650 ;; Argument handling according to FUN's TYPE is already done
651 ;; elsewhere: HANDLER, meval...
675 ;;; I/O cruft
696 ;; 9:02pm Monday, 18 May 1981 -GJC
697 ;; A function benchmark facility using trace utilities.
698 ;; This provides medium accuracy, enough for most user needs.
718 ,calls
759 "If true, then time spent inside calls to other timed functions is
763 ;; N.B. Doesn't even try to account for use of DYNAMIC CONTROL
764 ;; such as ERRSET ERROR and CATCH and THROW, as these are
765 ;; rare and the overhead for the unwind-protect is high.