From 1eebf8f55eda2a7e29b0e3f694281daefad68cac Mon Sep 17 00:00:00 2001 From: slava Date: Mon, 4 Dec 2006 06:00:08 +0000 Subject: [PATCH] Clarify in-thread documentation --- core/errors.facts | 6 +++--- core/handbook/dataflow.facts | 2 +- core/kernel.facts | 2 +- core/threads.facts | 12 ++++++++++-- core/tools/debugger.facts | 2 +- 5 files changed, 16 insertions(+), 8 deletions(-) diff --git a/core/errors.facts b/core/errors.facts index 12f1e3b66b..9610443486 100644 --- a/core/errors.facts +++ b/core/errors.facts @@ -28,18 +28,18 @@ HELP: throw ( error -- * ) HELP: catch { $values { "try" "a quotation" } { "error/f" "an object" } } -{ $description "Calls the " { $snippet "try" } " quotation. If an error is thrown in the dynamic extent of the quotation, restores the datastack and pushes the error. If the quotation returns successfully, outputs " { $link f } " without restoring the datastack." } +{ $description "Calls the " { $snippet "try" } " quotation. If an error is thrown in the dynamic extent of the quotation, restores the data stack and pushes the error. If the quotation returns successfully, outputs " { $link f } " without restoring the data stack." } { $notes "This word cannot differentiate between the case of " { $link f } " being thrown, and no error being thrown. You should never throw " { $link f } ", and you should also use other error handling combinators where possible." } { $see-also cleanup recover } ; HELP: cleanup { $values { "try" "a quotation" } { "cleanup" "a quotation" } } -{ $description "Calls the " { $snippet "try" } " quotation. If an exception is thrown in the dynamic extent of the " { $snippet "try" } " quotation, restores the datastack, calls the " { $snippet "cleanup" } " quotation, and rethrows the error. If the " { $snippet "try" } " quotation returns successfully, calls the " { $snippet "cleanup" } " quotation without restoring the datastack." } +{ $description "Calls the " { $snippet "try" } " quotation. If an exception is thrown in the dynamic extent of the " { $snippet "try" } " quotation, restores the data stack, calls the " { $snippet "cleanup" } " quotation, and rethrows the error. If the " { $snippet "try" } " quotation returns successfully, calls the " { $snippet "cleanup" } " quotation without restoring the data stack." } { $see-also catch recover } ; HELP: recover { $values { "try" "a quotation" } { "recovery" "a quotation with stack effect " { $snippet "( error -- )" } } } -{ $description "Calls the " { $snippet "try" } " quotation. If an exception is thrown in the dynamic extent of the " { $snippet "try" } " quotation, restores the datastack and calls the " { $snippet "recovery" } " quotation to handle the error." } +{ $description "Calls the " { $snippet "try" } " quotation. If an exception is thrown in the dynamic extent of the " { $snippet "try" } " quotation, restores the data stack and calls the " { $snippet "recovery" } " quotation to handle the error." } { $see-also catch cleanup } ; HELP: rethrow diff --git a/core/handbook/dataflow.facts b/core/handbook/dataflow.facts index 74f39ac301..1d88257b4a 100644 --- a/core/handbook/dataflow.facts +++ b/core/handbook/dataflow.facts @@ -100,7 +100,7 @@ ARTICLE: "interpreter" "The interpreter" { "If the end of the current quotation has been reached, the parent quotation is popped from the call stack and execution resumes from the saved location" } { "Otherwise, the interpreter performs an action depending on the type of the object at the instruction pointer:" { $list - { { $emphasis "Symbol word" } " - pushed on the datastack. See " { $link "symbols" } } + { { $emphasis "Symbol word" } " - pushed on the data stack. See " { $link "symbols" } } { { $emphasis "Compound word" } " - the associated quotation is called. See " { $link "colon-definition" } } { { $emphasis "Compiled or primitive word" } " - the interpreter jumps to machine code. See " { $link "primitives" } } { { $emphasis "Undefined word" } " - an error is raised. See " { $link "deferred" } } diff --git a/core/kernel.facts b/core/kernel.facts index 3d32e2bc9c..38bfb375cf 100644 --- a/core/kernel.facts +++ b/core/kernel.facts @@ -256,7 +256,7 @@ HELP: with HELP: keep-datastack { $values { "quot" "a quotation" } } -{ $description "Calls a quotation, saving the datastack before calling it and restoring it after it returns." } ; +{ $description "Calls a quotation, saving the data stack before calling it and restoring it after it returns." } ; HELP: die { $description "Starts the front-end processor (FEP), which is a low-level debugger which can inspect memory addresses and the like. The FEP is also entered when a critical error occurs." } ; diff --git a/core/threads.facts b/core/threads.facts index fa8d9ef8cb..30d47b100a 100644 --- a/core/threads.facts +++ b/core/threads.facts @@ -1,4 +1,4 @@ -USING: help threads kernel ; +USING: help threads kernel io ; HELP: run-queue { $values { "queue" "a queue" } } @@ -36,7 +36,15 @@ HELP: sleep HELP: in-thread { $values { "quot" "a quotation" } } -{ $description "Spawns a new thread. The new thread begins running immediately. If an unhandled error occurs in the thread, the error is logged to the default stream in the dynamic extent of the caller of this word." } ; +{ $description "Spawns a new thread. The new thread begins running immediately." +$terpri +"The new thread inherits the current data stack and name stack. The call stack initially contains the new quotation only, so when the quotation returns the thread stops. The catch stack contains a default handler which logs errors to the " { $link stdio } " stream." } +{ $examples + { $code "1 2 [ + . ] in-thread" } +} +{ $notes + "A higher-level concurrency library can be found in the " { $snippet "libs/concurrency" } " module; see " { $link "modules" } "." +} ; HELP: idle-thread { $description "Runs the idle thread, which services I/O requests and relinquishes control to the operating system until the next Factor thread has to wake up again." } diff --git a/core/tools/debugger.facts b/core/tools/debugger.facts index ad2811f65c..0c413106ce 100644 --- a/core/tools/debugger.facts +++ b/core/tools/debugger.facts @@ -37,7 +37,7 @@ HELP: print-error HELP: try { $values { "quot" "a quotation" } } -{ $description "Calls the quotation. If it throws an error, logs the error to the default stream and restores the datastack." } ; +{ $description "Calls the quotation. If it throws an error, logs the error to the default stream and restores the data stack." } ; HELP: expired-error. { $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." }