Document io.timeouts

core/io/io-docs.factor

@@ -21,7 +21,8 @@ $nl
 { $subsection make-span-stream }
 { $subsection make-block-stream }
 { $subsection make-cell-stream }
-{ $subsection stream-write-table } ;
+{ $subsection stream-write-table }
+{ $see-also "io.timeouts" } ;
 
 ARTICLE: "stdio" "The default stream"
 "Various words take an implicit stream parameter from a variable to reduce stack shuffling."

extra/help/handbook/handbook.factor

@@ -157,7 +157,8 @@ ARTICLE: "io" "Input and output"
 "Advanced features:"
 { $subsection "io.launcher" }
 { $subsection "io.mmap" }
-{ $subsection "io.monitors" } ;
+{ $subsection "io.monitors" }
+{ $subsection "io.timeouts" } ;
 
 ARTICLE: "tools" "Developer tools"
 { $subsection "tools.annotations" }

extra/io/launcher/launcher-docs.factor

@@ -76,6 +76,9 @@ HELP: +append-environment+
 $nl
 "This is used in situations where you want a spawn child process with some overridden environment variables." } ;
 
+HELP: +timeout+
+{ $description "Launch descriptor key. If set, specifies a maximum running time for the process. If the process runs longer than this time, it will be killed." } ;
+
 HELP: default-descriptor
 { $description "Association storing default values for launch descriptor keys." } ;
 
@@ -94,22 +97,16 @@ HELP: run-process*
 
 HELP: >descriptor
 { $values { "desc" "a launch descriptor" } { "desc" "a launch descriptor" } }
-{ $description "Creates a launch descriptor from an object, which must be one of the following:"
-    { $list
-        { "a string -- this is wrapped in a launch descriptor with a single " { $link +command+ } " key" }
-        { "a sequence of strings -- this is wrapped in a launch descriptor with a single " { $link +arguments+ } " key" }
-        { "an association, used to set launch parameters for additional control" }
-    }
-} ;
+{ $description "Creates a launch descriptor from an object. See " { $link "io.launcher.descriptors" } " for details." } ;
 
 HELP: run-process
 { $values { "desc" "a launch descriptor" } { "process" process } }
-{ $description "Launches a process. The object can either be a string, a sequence of strings or a launch descriptor. See " { $link >descriptor } " for details." }
+{ $description "Launches a process. The object can either be a string, a sequence of strings or a launch descriptor. See " { $link "io.launcher.descriptors" } " for details." }
 { $notes "The output value can be passed to " { $link wait-for-process } " to get an exit code." } ;
 
 HELP: run-detached
 { $values { "desc" "a launch descriptor" } { "process" process } }
-{ $contract "Launches a process without waiting for it to complete. The object can either be a string, a sequence of strings or a launch descriptor. See " { $link >descriptor } " for details." }
+{ $contract "Launches a process without waiting for it to complete. The object can either be a string, a sequence of strings or a launch descriptor. See " { $link "io.launcher.descriptors" } " for details." }
 { $notes
     "This word is functionally identical to passing a launch descriptor to " { $link run-process } " having the " { $link +detached+ } " key set."
     $nl
@@ -162,25 +159,27 @@ HELP: wait-for-process
 { $values { "process" process } { "status" integer } }
 { $description "If the process is still running, waits for it to exit, otherwise outputs the exit code immediately. Can be called multiple times on the same process." } ;
 
-ARTICLE: "io.launcher" "Launching OS processes"
-"The " { $vocab-link "io.launcher" } " vocabulary implements cross-platform process launching."
-$nl
-"Words which launch processes can take either a command line string, a sequence of command line arguments, or a launch descriptor:"
+ARTICLE: "io.launcher.descriptors" "Launch descriptors"
+"Words which launch processes can take either a command line string, a sequence of command line arguments, or an assoc:"
 { $list
-    { "strings are wrapped in a launch descriptor with a single " { $link +command+ } " key" }
-    { "sequences of strings are wrapped in a launch descriptor with a single " { $link +arguments+ } " key" }
-    { "launch descriptors are associations, which can set extra launch parameters for finer control" }
+    { "strings are wrapped in an assoc with a single " { $link +command+ } " key" }
+    { "sequences of strings are wrapped in an assoc with a single " { $link +arguments+ } " key" }
+    { "associations can be passed in, which allows finer control over launch parameters" }
 }
-"A launch descriptor is an association containing keys from the below set:"
+"The associations can contain the following keys:"
 { $subsection +command+ }
 { $subsection +arguments+ }
 { $subsection +detached+ }
 { $subsection +environment+ }
 { $subsection +environment-mode+ }
-"Redirecting standard input and output to files:"
+{ $subsection +timeout+ }
 { $subsection +stdin+ }
 { $subsection +stdout+ }
-{ $subsection +stderr+ }
+{ $subsection +stderr+ } ;
+
+ARTICLE: "io.launcher" "Launching OS processes"
+"The " { $vocab-link "io.launcher" } " vocabulary implements cross-platform process launching."
+{ $subsection "io.launcher.descriptors" }
 "The following words are used to launch processes:"
 { $subsection run-process }
 { $subsection run-detached }
@@ -193,6 +192,7 @@ $nl
 "A class representing an active or finished process:"
 { $subsection process }
 "Waiting for a process to end, or getting the exit code of a finished process:"
-{ $subsection wait-for-process } ;
+{ $subsection wait-for-process }
+"Processes support the " { $link "io.timeouts" } "; the timeout specifies an upper bound on the running time of the process." ;
 
 ABOUT: "io.launcher"

extra/io/launcher/launcher.factor

@@ -66,11 +66,15 @@ SYMBOL: +append-environment+
         { +replace-environment+ [ ] }
     } case ;
 
-GENERIC: >descriptor ( desc -- desc )
+: string-array? ( obj -- ? )
+    dup sequence? [ [ string? ] all? ] [ drop f ] if ;
 
-M: string >descriptor +command+ associate ;
-M: sequence >descriptor +arguments+ associate ;
-M: assoc >descriptor >hashtable ;
+: >descriptor ( desc -- desc )
+    {
+        { [ dup string? ] [ +command+ associate ] }
+        { [ dup string-array? ] [ +arguments+ associate ] }
+        { [ dup assoc? ] [ >hashtable ] }
+    } cond ;
 
 HOOK: run-process* io-backend ( desc -- handle )
 

extra/io/timeouts/timeouts-docs.factor

@@ -0,0 +1,32 @@
+IN: io.timeouts
+USING: help.markup help.syntax math kernel ;
+
+HELP: get-lapse
+{ $values { "obj" object } { "lapse" lapse } }
+{ $contract "Outputs an object's timeout lapse descriptor." } ;
+
+HELP: set-timeout
+{ $values { "ms" integer } { "obj" object } }
+{ $contract "Sets an object's timeout, in milliseconds." }
+{ $notes "The default implementation delegates the call to the object's timeout lapse descriptor." } ;
+
+HELP: timed-out
+{ $values { "obj" object } }
+{ $contract "Handles a timeout, usually by waking up all threads waiting on the object." } ;
+
+HELP: with-timeout
+{ $values { "obj" object } { "quot" "a quotation with stack effect " { $snippet "( obj -- )" } } }
+{ $description "Applies the quotation to the object. If the object's timeout expires before the quotation returns, " { $link timed-out } " is called on the object." } ;
+
+ARTICLE: "io.timeouts" "I/O timeout protocol"
+"Streams and processes support optional timeouts, which impose an upper bound on the length of time for which an operation on these objects can block. Timeouts are used in network servers to prevent malicious clients from holding onto connections forever, and to ensure that runaway processes get killed."
+{ $subsection set-timeout }
+"The I/O timeout protocol can be implemented by any class wishing to support timeouts on blocking operations."
+{ $subsection get-lapse }
+{ $subsection timed-out }
+"A combinator to be used in operations which can time out:"
+{ $subsection with-timeout }
+{ $see-also "stream-protocol" "io.launcher" }
+;
+
+ABOUT: "io.timeouts"

extra/io/unix/linux/linux.factor

@@ -1,9 +1,10 @@
 ! Copyright (C) 2008 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
-USING: kernel io.backend io.monitors io.monitors.private io.files
-io.buffers io.nonblocking io.unix.backend io.unix.select
-io.unix.launcher unix.linux.inotify assocs namespaces threads
-continuations init math alien.c-types alien vocabs.loader ;
+USING: kernel io.backend io.monitors io.monitors.private
+io.files io.buffers io.nonblocking io.timeouts io.unix.backend
+io.unix.select io.unix.launcher unix.linux.inotify assocs
+namespaces threads continuations init math alien.c-types alien
+vocabs.loader ;
 IN: io.unix.linux
 
 TUPLE: linux-io ;