basis/io/ports/ports-docs.factor

   1 USING: io io.buffers io.backend help.markup help.syntax kernel
   2 byte-arrays sbufs words continuations destructors
   3 byte-vectors classes ;
   4 IN: io.ports
   5
   6 ARTICLE: "io.ports" "Non-blocking I/O implementation"
   7 "On Windows and Unix, Factor implements blocking file and network streams on top of a non-blocking I/O substrate, ensuring that Factor threads will yield when performing I/O. This substrate is implemented in the " { $vocab-link "io.ports" } " vocabulary."
   8 $nl
   9 "A " { $emphasis "port" } " is a stream using non-blocking I/O substrate:"
  10 { $subsection port }
  11 { $subsection <port> }
  12 { $subsection <buffered-port> }
  13 "Input ports:"
  14 { $subsection input-port }
  15 { $subsection <input-port> }
  16 "Output ports:"
  17 { $subsection output-port }
  18 { $subsection <output-port> }
  19 "Global native I/O protocol:"
  20 { $subsection io-backend }
  21 { $subsection init-io }
  22 { $subsection init-stdio }
  23 { $subsection io-multiplex }
  24 "Per-port native I/O protocol:"
  25 { $subsection (wait-to-read) }
  26 { $subsection (wait-to-write) }
  27 "Additionally, the I/O backend must provide an implementation of the " { $link dispose } " generic word." ;
  28
  29 ABOUT: "io.ports"
  30
  31 HELP: port
  32 { $class-description "Instances of this class present a blocking stream interface on top of an underlying non-blocking I/O system, giving the illusion of blocking by yielding the thread which is waiting for input or output." } ;
  33
  34 HELP: input-port
  35 { $class-description "The class of ports implementing the input stream protocol." } ;
  36
  37 HELP: output-port
  38 { $class-description "The class of ports implementing the output stream protocol." } ;
  39
  40 HELP: <port>
  41 { $values { "handle" "a native handle identifying an I/O resource" } { "class" class } { "port" "a new " { $link port } } }
  42 { $description "Creates a new " { $link port } " with no buffer." }
  43 $low-level-note ;
  44
  45 HELP: <buffered-port>
  46 { $values { "handle" "a native handle identifying an I/O resource" } { "class" class } { "port" "a new " { $link port } } }
  47 { $description "Creates a new " { $link port } " using the specified native handle and a default-sized I/O buffer." }
  48 $low-level-note ;
  49
  50 HELP: <input-port>
  51 { $values { "handle" "a native handle identifying an I/O resource" } { "input-port" "a new " { $link input-port } } }
  52 { $description "Creates a new " { $link input-port } " using the specified native handle and a default-sized input buffer." }
  53 $low-level-note ;
  54
  55 HELP: <output-port>
  56 { $values { "handle" "a native handle identifying an I/O resource" } { "output-port" "a new " { $link output-port } } }
  57 { $description "Creates a new " { $link output-port } " using the specified native handle and a default-sized input buffer." }
  58 $low-level-note ;
  59
  60 HELP: (wait-to-read)
  61 { $values { "port" input-port } }
  62 { $contract "Suspends the current thread until the port's buffer has data available for reading." } ;
  63
  64 HELP: wait-to-read
  65 { $values { "port" input-port } { "eof?" "a boolean" } }
  66 { $description "If the port's buffer has unread data, returns immediately, otherwise suspends the current thread until some data is available for reading. If the buffer was empty and no more data could be read, outputs " { $link t } " to indicate end-of-file; otherwise outputs " { $link f } "." } ;