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 { $subsections
  11     port
  12     <port>
  13     <buffered-port>
  14 }
  15 "Input ports:"
  16 { $subsections
  17     input-port
  18     <input-port>
  19 }
  20 "Output ports:"
  21 { $subsections
  22     output-port
  23     <output-port>
  24 }
  25 "Global native I/O protocol:"
  26 { $subsections
  27     io-backend
  28     init-io
  29     init-stdio
  30     io-multiplex
  31 }
  32 "Per-port native I/O protocol:"
  33 { $subsections
  34     (wait-to-read)
  35     (wait-to-write)
  36 }
  37 "Additionally, the I/O backend must provide an implementation of the " { $link dispose } " generic word." ;
  38
  39 ABOUT: "io.ports"
  40
  41 HELP: port
  42 { $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." } ;
  43
  44 HELP: input-port
  45 { $class-description "The class of ports implementing the input stream protocol." } ;
  46
  47 HELP: output-port
  48 { $class-description "The class of ports implementing the output stream protocol." } ;
  49
  50 HELP: <port>
  51 { $values { "handle" "a native handle identifying an I/O resource" } { "class" class } { "port" "a new " { $link port } } }
  52 { $description "Creates a new " { $link port } " with no buffer." }
  53 $low-level-note ;
  54
  55 HELP: <buffered-port>
  56 { $values { "handle" "a native handle identifying an I/O resource" } { "class" class } { "port" "a new " { $link port } } }
  57 { $description "Creates a new " { $link port } " using the specified native handle and a default-sized I/O buffer." }
  58 $low-level-note ;
  59
  60 HELP: <input-port>
  61 { $values { "handle" "a native handle identifying an I/O resource" } { "input-port" "a new " { $link input-port } } }
  62 { $description "Creates a new " { $link input-port } " using the specified native handle and a default-sized input buffer." }
  63 $low-level-note ;
  64
  65 HELP: <output-port>
  66 { $values { "handle" "a native handle identifying an I/O resource" } { "output-port" "a new " { $link output-port } } }
  67 { $description "Creates a new " { $link output-port } " using the specified native handle and a default-sized input buffer." }
  68 $low-level-note ;
  69
  70 HELP: (wait-to-read)
  71 { $values { "port" input-port } }
  72 { $contract "Suspends the current thread until the port's buffer has data available for reading." } ;
  73
  74 HELP: wait-to-read
  75 { $values { "port" input-port } { "eof?" boolean } }
  76 { $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 } "." } ;