basis/io/timeouts/timeouts-docs.factor

   1 IN: io.timeouts
   2 USING: help.markup help.syntax math kernel calendar ;
   3
   4 HELP: timeout
   5 { $values { "obj" object } { "dt/f" { $maybe duration } } }
   6 { $contract "Outputs an object's timeout." } ;
   7
   8 HELP: set-timeout
   9 { $values { "dt/f" { $maybe duration } } { "obj" object } }
  10 { $contract "Sets an object's timeout." }
  11 { $examples "Waits five seconds for a process that sleeps for ten seconds:"
  12   { $unchecked-example
  13     "USING: calendar io.launcher io.timeouts kernel ;"
  14     "\"sleep 10\" >process 5 seconds over set-timeout run-process"
  15     "Process was killed as a result of a call to"
  16     "kill-process, or a timeout"
  17   }
  18 } ;
  19
  20 HELP: cancel-operation
  21 { $values { "obj" object } }
  22 { $contract "Handles a timeout, usually by waking up all threads waiting on the object." } ;
  23
  24 HELP: with-timeout
  25 { $values { "obj" object } { "quot" { $quotation ( obj -- ) } } }
  26 { $description "Applies the quotation to the object. If the object's timeout expires before the quotation returns, " { $link cancel-operation } " is called on the object." } ;
  27
  28 ARTICLE: "io.timeouts" "I/O timeout protocol"
  29 "Streams, processes and monitors 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."
  30 { $subsections
  31     timeout
  32     set-timeout
  33 }
  34 "The I/O timeout protocol can be implemented by any class wishing to support timeouts on blocking operations."
  35 { $subsections cancel-operation }
  36 "A combinator to be used in operations which can time out:"
  37 { $subsections with-timeout }
  38 { $see-also "stream-protocol" "io.launcher" "io.monitors" } ;
  39
  40 ABOUT: "io.timeouts"