1 /* Copyright (C) 2001-2006 Artifex Software, Inc. 2 All Rights Reserved. 3 4 This software is provided AS-IS with no warranty, either express or 5 implied. 6 7 This software is distributed under license and may not be copied, modified 8 or distributed except as expressly authorized under the terms of that 9 license. Refer to licensing information at http://www.artifex.com/ 10 or contact Artifex Software, Inc., 7 Mt. Lassen Drive - Suite A-134, 11 San Rafael, CA 94903, U.S.A., +1(415)492-9861, for further information. 12 */ 13 /* $Id: estack.h 9043 2008-08-28 22:48:19Z giles $ */ 14 /* Definitions for the execution stack */ 15 16 #ifndef estack_INCLUDED 17 # define estack_INCLUDED 18 19 #include "iestack.h" 20 #include "icstate.h" /* for access to exec_stack */ 21 22 /* Define access to the cached current_file pointer. */ 23 #define esfile (iexec_stack.current_file) 24 #define esfile_clear_cache() estack_clear_cache(&iexec_stack) 25 #define esfile_set_cache(pref) estack_set_cache(&iexec_stack, pref) 26 #define esfile_check_cache() estack_check_cache(&iexec_stack) 27 28 /* Define the execution stack pointers for operators. */ 29 #define iexec_stack (i_ctx_p->exec_stack) 30 #define e_stack (iexec_stack.stack) 31 32 #define esbot (e_stack.bot) 33 #define esp (e_stack.p) 34 #define estop (e_stack.top) 35 36 /* 37 * The execution stack holds several different kinds of objects (refs) 38 * related to executing PostScript code: 39 * 40 * - Procedures being executed are held here. They always have 41 * type = t_array, t_mixedarray, or t_shortarray, with a_executable set. 42 * More specifically, the e-stack holds the as yet unexecuted tail of the 43 * procedure. 44 * 45 * - if, ifelse, etc. push arguments to be executed here. They may be 46 * any kind of object whatever. Similarly, looping operators (forall, for, 47 * etc.) push the procedure that is to be executed for each iteration. 48 * 49 * - Control operators (filenameforall, for, repeat, loop, forall, 50 * pathforall, run, stopped, ...) use continuations as described below. 51 * 52 * Note that there are many internal operators that need to use 53 * continuations -- for example, all the 'show' operators, since they may 54 * call out to BuildChar procedures. 55 */ 56 57 /* 58 * Because the Ghostscript architecture doesn't allow recursive calls to the 59 * interpreter, any operator that needs to call out to PostScript code (for 60 * example, the 'show' operators calling a BuildChar procedure, or setscreen 61 * sampling a spot function) must use a continuation -- an internal 62 * "operator" procedure that continues the logical thread of execution after 63 * the callout. Operators needing to use continuations push the following 64 * onto the execution stack (from bottom to top): 65 * 66 * - An e-stack mark -- an executable null that indicates the bottom of 67 * the block associated with a callout. (This should not be confused 68 * with a PostScript mark, a ref of type t_mark on the operand stack.) 69 * See make_mark_estack and push_mark_estack below. The value.opproc 70 * member of the e-stack mark contains a procedure to execute in case 71 * the e-stack is stripped back beyond this point by a 'stop' or 72 * 'exit': see pop_estack in zcontrol.c for details. 73 * 74 * - Any number of refs holding information that the continuation 75 * operator needs -- i.e., the saved logical state of the thread of 76 * execution. For example, 'for' stores the procedure, the current 77 * value, the increment, and the limit here. 78 * 79 * - The continuation procedure itself -- the pseudo-operator to be 80 * called after returns from the interpreter callout. See 81 * make_op_estack and push_op_estack below. 82 * 83 * - The PostScript procedure for the interpreter to execute. 84 * 85 * The operator then returns o_push_estack, indicating to the interpreter 86 * that the operator has pushed information on the e-stack for the 87 * interpreter to process. 88 * 89 * When the interpreter finishes executing the PostScript procedure, it pops 90 * the next item off the e-stack, which is the continuation procedure. When 91 * the continuation procedure gets control, the top of the e-stack (esp) 92 * points just below the continuation procedure slot -- i.e., to the topmost 93 * saved state item. The continuation procedure normally pops all of the 94 * saved state, and the e-stack mark, and continues execution normally, 95 * eventually returning o_pop_estack to tell the interpreter that the 96 * "operator" has popped information off the e-stack. (Loop operators do 97 * something a bit more efficient than popping the information and then 98 * pushing it again: refer to the examples in zcontrol.c for details.) 99 * 100 * Continuation procedures are called just like any other operator, so they 101 * can call each other, or be called from ordinary operator procedures, as 102 * long as the e-stack is in the right state. The most complex example of 103 * this is probably the Type 1 character rendering code in zchar1.c, where 104 * continuation procedures either call each other directly or call out to 105 * the interpreter to execute optional PostScript procedures like CDevProc. 106 */ 107 108 /* Macro for marking the execution stack */ 109 #define make_mark_estack(ep, es_idx, proc)\ 110 make_tasv(ep, t_null, a_executable, es_idx, opproc, proc) 111 #define push_mark_estack(es_idx, proc)\ 112 (++esp, make_mark_estack(esp, es_idx, proc)) 113 #define r_is_estack_mark(ep)\ 114 r_has_type_attrs(ep, t_null, a_executable) 115 #define estack_mark_index(ep) r_size(ep) 116 #define set_estack_mark_index(ep, es_idx) r_set_size(ep, es_idx) 117 118 /* Macro for pushing an operator on the execution stack */ 119 /* to represent a continuation procedure */ 120 #define make_op_estack(ep, proc)\ 121 make_oper(ep, 0, proc) 122 #define push_op_estack(proc)\ 123 (++esp, make_op_estack(esp, proc)) 124 125 /* Macro to ensure enough room on the execution stack */ 126 #define check_estack(n)\ 127 if ( esp > estop - (n) )\ 128 { int es_code_ = ref_stack_extend(&e_stack, n);\ 129 if ( es_code_ < 0 ) return es_code_;\ 130 } 131 132 /* Macro to ensure enough entries on the execution stack */ 133 #define check_esp(n)\ 134 if ( esp < esbot + ((n) - 1) )\ 135 { e_stack.requested = (n); return_error(e_ExecStackUnderflow); } 136 137 /* Define the various kinds of execution stack marks. */ 138 #define es_other 0 /* internal use */ 139 #define es_show 1 /* show operators */ 140 #define es_for 2 /* iteration operators */ 141 #define es_stopped 3 /* stopped operator */ 142 143 /* 144 * Pop a given number of elements off the execution stack, 145 * executing cleanup procedures as necessary. 146 */ 147 void pop_estack(i_ctx_t *, uint); 148 149 /* 150 * The execution stack is implemented as a linked list of blocks; 151 * operators that can push or pop an unbounded number of values, or that 152 * access the entire e-stack, must take this into account. These are: 153 * exit .stop .instopped countexecstack execstack currentfile 154 * .execn 155 * pop_estack(exit, stop, error recovery) 156 * gs_show_find(all the show operators) 157 * In addition, for e-stack entries created by control operators, we must 158 * ensure that the mark and its data are never separated. We do this 159 * by ensuring that when splitting the top block, at least N items 160 * are kept in the new top block above the bottommost retained mark, 161 * where N is the largest number of data items associated with a mark. 162 * Finally, in order to avoid specific checks for underflowing a block, 163 * we put a guard entry at the bottom of each block except the top one 164 * that contains a procedure that returns an internal "exec stack block 165 * underflow" error. 166 */ 167 168 #endif /* estack_INCLUDED */ 169