core/debugger/debugger-docs.factor

   1 USING: alien arrays generic generic.math help.markup help.syntax
   2 kernel math memory strings sbufs vectors io io.files classes
   3 help generic.standard continuations system debugger.private
   4 io.files.private listener ;
   5 IN: debugger
   6
   7 ARTICLE: "errors-assert" "Assertions"
   8 "Some words to make assertions easier to enforce:"
   9 { $subsection assert }
  10 { $subsection assert= }
  11 "Runtime stack depth checking:"
  12 { $subsection depth }
  13 { $subsection assert-depth } ;
  14
  15 ARTICLE: "debugger" "The debugger"
  16 "Caught errors can be logged in human-readable form:"
  17 { $subsection print-error }
  18 { $subsection try }
  19 "User-defined errors can have customized printed representation by implementing a generic word:"
  20 { $subsection error. }
  21 "A number of words facilitate interactive debugging of errors:"
  22 { $subsection :s }
  23 { $subsection :r }
  24 { $subsection :c }
  25 { $subsection :get }
  26 "Most types of errors are documented, and the documentation is instantly accessible:"
  27 { $subsection :help }
  28 "If the error was restartable, a list of restarts is also printed, and a numbered restart can be invoked:"
  29 { $subsection :1 }
  30 { $subsection :2 }
  31 { $subsection :3 }
  32 { $subsection :res }
  33 "Assertions:"
  34 { $subsection "errors-assert" }
  35 "You can read more about error handling in " { $link "errors" } "." ;
  36
  37 ABOUT: "debugger"
  38
  39 HELP: :s
  40 { $description "Prints the data stack at the time of the most recent error. Used for interactive debugging." } ;
  41
  42 HELP: :r
  43 { $description "Prints the retain stack at the time of the most recent error. Used for interactive debugging." } ;
  44
  45 HELP: :c
  46 { $description "Prints the call stack at the time of the most recent error. Used for interactive debugging." } ;
  47
  48 HELP: :get
  49 { $values { "variable" "an object" } { "value" "the value, or f" } }
  50 { $description "Looks up the value of a variable at the time of the most recent error." } ;
  51
  52 HELP: :res
  53 { $values { "n" "a positive integer" } }
  54 { $description "Continues executing the " { $snippet "n" } "th restart. Since restarts may only be invoked once, this resets the " { $link restarts } " global variable." } ;
  55
  56 HELP: :1
  57 { $description "A shortcut for invoking the first restart." } ;
  58
  59 HELP: :2
  60 { $description "A shortcut for invoking the second restart." } ;
  61
  62 HELP: :3
  63 { $description "A shortcut for invoking the third restart." } ;
  64
  65 HELP: error.
  66 { $values { "error" "an error" } }
  67 { $contract "Print an error to " { $link output-stream } ". You can define methods on this generic word to print human-readable messages for custom errors." }
  68 { $notes "Code should call " { $link print-error } " instead, which handles the case where the printing of the error itself throws an error." } ;
  69
  70 HELP: error-help
  71 { $values { "error" "an error" } { "topic" "an article name or word" } }
  72 { $contract "Outputs a help article which explains the error." } ;
  73
  74 { error-help :help } related-words
  75
  76 HELP: print-error
  77 { $values { "error" "an error" } }
  78 { $description "Print an error to " { $link output-stream } "." }
  79 { $notes "This word is called by the listener and other tools which report caught errors to the user." } ;
  80
  81 HELP: restarts.
  82 { $description "Print a list of restarts for the most recently thrown error to " { $link output-stream } "." } ;
  83
  84 HELP: try
  85 { $values { "quot" "a quotation" } }
  86 { $description "Attempts to call a quotation; if it throws an error, the error is printed to " { $link output-stream } ", stacks are restored, and execution continues after the call to " { $link try } "." }
  87 { $examples
  88     "The following example prints an error and keeps going:"
  89     { $code
  90         "[ \"error\" throw ] try"
  91         "\"still running...\" print"
  92     }
  93     { $link "listener" } " uses " { $link try } " to recover from user errors."
  94 } ;
  95
  96 HELP: expired-error.
  97 { $error-description "Thrown by " { $link alien-address } " and " { $link alien-invoke } " if an " { $link alien } " object passed in as a parameter has expired. Alien objects expire if they are saved an image which is subsequently loaded; this prevents a certain class of programming errors, usually attempts to use uninitialized objects, since holding a C address is meaningless between sessions." }
  98 { $notes "You can check if an alien object has expired by calling " { $link expired? } "." } ;
  99
 100 HELP: io-error.
 101 { $error-description "Thrown by the C streams I/O primitives if an I/O error occurs." } ;
 102
 103 HELP: type-check-error.
 104 { $error-description "Thrown by various primitives if one of the inputs does not have the expected type. Generic words throw " { $link no-method } " and " { $link no-math-method } " errors in such cases instead." } ;
 105
 106 HELP: divide-by-zero-error.
 107 { $error-description "This error is thrown when " { $link / } " or " { $link /i } " is called with with a zero denominator." }
 108 { $see-also "division-by-zero" } ;
 109
 110 HELP: signal-error.
 111 { $error-description
 112     "Thrown by the Factor VM when a Unix signal is received. While signal numbers are system-specific, the following are relatively standard:"
 113     { $list
 114         { "4 - Illegal instruction. If you see this error, it is a bug in Factor's compiler and should be reported." }
 115         { "8 - Arithmetic exception. Most likely a divide by zero in " { $link /i } "." }
 116         { "10, 11 - Memory protection fault. This error suggests invalid values are being passed to C functions by an " { $link alien-invoke } ". Factor also uses memory protection to trap stack underflows and overflows, but usually these are reported as their own errors. Sometimes they'll show up as a generic signal 11, though." }
 117     }
 118     "The Windows equivalent of a signal 11 is a SEH fault. When one occurs, the runtime throws a singal error, even though it does not correspond to a Unix signal."
 119 } ;
 120
 121 HELP: array-size-error.
 122 { $error-description "Thrown by " { $link <array> } ", " { $link <string> } ", " { $link <vector> } " and " { $link <sbuf> } " if the specified capacity is negative or too large." } ;
 123
 124 HELP: c-string-error.
 125 { $error-description "Thrown by " { $link alien-invoke } " and various primitives if a string containing null bytes, or characters with values higher than 255 is passed in where a C string is expected. See " { $link "c-strings" } "." } ;
 126
 127 HELP: ffi-error.
 128 { $error-description "Thrown by " { $link dlopen } " and " { $link dlsym } " if a problem occurs while loading a native library or looking up a symbol. See " { $link "alien" } "." } ;
 129
 130 HELP: heap-scan-error.
 131 { $error-description "Thrown if " { $link next-object } " is called outside of a " { $link begin-scan } "/" { $link end-scan } " pair." } ;
 132
 133 HELP: undefined-symbol-error.
 134 { $error-description "Thrown if a previously-compiled " { $link alien-invoke } " call refers to a native library symbol which no longer exists." } ;
 135
 136 HELP: datastack-underflow.
 137 { $error-description "Thrown by the Factor VM if an attempt is made to pop elements from an empty data stack." }
 138 { $notes "You can use the stack effect tool to statically check stack effects of quotations. See " { $link "inference" } "." } ;
 139
 140 HELP: datastack-overflow.
 141 { $error-description "Thrown by the Factor VM if an attempt is made to push elements on a full data stack." }
 142 { $notes "This error usually indicates a run-away recursion, however if you legitimately need a data stack larger than the default, see " { $link "runtime-cli-args" } "." } ;
 143
 144 HELP: retainstack-underflow.
 145 { $error-description "Thrown by the Factor VM if " { $link r> } " is called while the retain stack is empty." }
 146 { $notes "You can use the stack effect tool to statically check stack effects of quotations. See " { $link "inference" } "." } ;
 147
 148 HELP: retainstack-overflow.
 149 { $error-description "Thrown by the Factor VM if " { $link >r } " is called when the retain stack is full." }
 150 { $notes "This error usually indicates a run-away recursion, however if you legitimately need a retain stack larger than the default, see " { $link "runtime-cli-args" } "." } ;
 151
 152 HELP: memory-error.
 153 { $error-description "Thrown by the Factor VM if an invalid memory access occurs." }
 154 { $notes "This can be a result of incorrect usage of C library interface words, a bug in the compiler, or a bug in the VM." } ;
 155
 156 HELP: primitive-error.
 157 { $error-description "Thrown by the Factor VM if an unsupported primitive word is called." }
 158 { $notes "This word is only ever thrown on Windows CE, where the " { $link cwd } ", " { $link cd } ", and " { $link os-env } " primitives are unsupported." } ;
 159
 160 HELP: assert
 161 { $values { "got" "the obtained value" } { "expect" "the expected value" } }
 162 { $description "Throws an " { $link assert } " error." }
 163 { $error-description "Thrown when a unit test or other assertion fails." } ;
 164
 165 { assert assert-depth } related-words
 166
 167 HELP: depth
 168 { $values { "n" "a non-negative integer" } }
 169 { $description "Outputs the number of elements on the data stack." } ;
 170
 171 HELP: assert-depth
 172 { $values { "quot" "a quotation" } }
 173 { $description "Runs a quotation. Throws an error if the total number of elements on the stack is not the same before and after the quotation runs." } ;
 174
 175 HELP: init-debugger
 176 { $description "Called on startup to set a pair of hooks which allow the " { $link throw } " word to function." } ;