| blob | b0caf5f40fee7dfe5d7df886f311e143b018cfee |
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!
284 ;; Pretty sure this next property assignment is clobbered by TRACE-FSHADOW,
285 ;; however, the assignment is conditional there, so I don't know 100%.
301 ;; Placing the TRACE functional hook.
302 ;; Because the function properties in macsyma are used by the EDITOR, SAVE,
303 ;; and GRIND commands it is not possible to simply replace the function
304 ;; being traced with a hook and to store the old definition someplace.
305 ;; [We do know how to cons up machine-code hooks on the fly, so that
306 ;; is not stopping us].
309 ;; This data should be formalized somehow at the time of
310 ;; definition of the DEFining form.
329 ; We're tracing an mexpr with special evaluation rules (mfexpr).
330 ; Let's put a Maxima lambda expression on the plist that calls
331 ; the trace hook. Then in the evaluator we can just have mlambda
332 ; do the work for us.
333 ;
334 ; If there is not a rest argument in the mexpr's lambda list
335 ; then this newly-constructed lambda expression just does a
336 ; funcall. If there is a rest argument then it requires a
337 ; little more work.
346 ; This is the mfexpr+mlexpr case (we have at
347 ; least one quoted arg and a rest arg).
348 ;
349 ; The use of call-hook here is basically like
350 ;
351 ; `(($apply) ,value
352 ; (($append)
353 ; ((mlist) ,@(butlast params))
354 ; ,(car (last params))))
355 ;
356 ; but faster. We just have to construct
357 ; things so simplifya doesn't barf on any
358 ; intermediate expressions.
371 ;; At this point, we know that FUN is traced.
383 ;;--- trace-fsymeval :: find original function
384 ;; fun : a function which is being traced. The original definition may
385 ;; be hidden on the property list behind the shadow function.
386 ;;
402 ;;; The handling of a traced call.
407 ;; is by far the best dynamic binding generally available.
412 ;; We really want to (BINDF (TRACE-LEVEL FUN) (1+ (TRACE-LEVEL FUN)) ...)
413 ;; (Think about PROGV and SETF and BINDF. If the trace object where
414 ;; a closure, then we want to fluid bind instance variables.)
434 ;; We were called by the trace-handler or by $untrace and the function
435 ;; fun is to be untraced.
475 ;; The (Trace-options function) access is not optimized to take place
476 ;; only once per trace-handle call. This is so that the user may change
477 ;; options during his break loops.
478 ;; Question: Should we bind return-to-trace-handle to NIL when we
479 ;; call the user's predicate? He has control over his own lossage.
490 nil)))
506 largs)))
515 " "
545 largs))
552 ; If trace_break_arg is the same (in the sense of eq) now
553 ; as when we started the breakpoint, then return all of the
554 ; original return values from the function. This means if
555 ; the user sets trace_break_arg but its value is eq to its
556 ; original value (which is only the primary return value
557 ; from the original function) then we still return the extra
558 ; values (if there are any). I (kjak) don't think this is
559 ; strictly correct, but we can try to fix it up later if
560 ; anyone ever really cares about this corner case involving
561 ; multiple return values, exit breakpoints and setting
562 ; trace_break_arg to the same value it started with.
564 ret-vals
566 ret-vals))
585 dlist
588 ;; I GUESS ALL OF THE STRINGS IN THIS FUNCTION NEED TO BE GETTEXT'D TOO
589 ;; JUST CAN'T BRING MYSELF TO DO IT
593 "Retry with same arguments?"
594 "Retry with new arguments?"
597 "at level" level
607 "Enter new argument list for"
614 ;;; application dispatch, and the consing up of the trace hook.
624 fun))
625 try)
629 ;; The semantics of $TRANSRUN are herein taken from DESCRIBE,
630 ;; a careful reading of MEVAL1 reveals, well... I've promised to watch
631 ;; my language in these comments.
637 ;; the default, so its really a waste to have looked for
638 ;; those mprops. Its better to fix the crock than to
639 ;; optimize this though!
652 ;; Argument handling according to FUN's TYPE is already done
653 ;; elsewhere: HANDLER, meval...
672 ;;; I/O cruft
693 ;; 9:02pm Monday, 18 May 1981 -GJC
694 ;; A function benchmark facility using trace utilities.
695 ;; This provides medium accuracy, enough for most user needs.
715 ,calls
756 "If true, then time spent inside calls to other timed functions is
760 ;; N.B. Doesn't even try to account for use of DYNAMIC CONTROL
761 ;; such as ERRSET ERROR and CATCH and THROW, as these are
762 ;; rare and the overhead for the unwind-protect is high.