basis/io/buffers/buffers-docs.factor

   1 USING: alien byte-arrays destructors help.markup help.syntax
   2 kernel math ;
   3 IN: io.buffers
   4
   5 ARTICLE: "buffers" "Locked I/O buffers"
   6 "I/O buffers are first-in-first-out queues of bytes."
   7 $nl
   8 "Buffers are backed by manually allocated storage that does not get moved by the garbage collector; they are also low-level and sacrifice error checking for efficiency."
   9 $nl
  10 "Buffers are used to implement native I/O backends."
  11 $nl
  12 "Buffer words are found in the " { $vocab-link "io.buffers" } " vocabulary."
  13 { $subsections
  14     buffer
  15     <buffer>
  16 }
  17 "Buffers must be manually deallocated by calling " { $link dispose } "."
  18 $nl
  19 "Buffer operations:"
  20 { $subsections
  21     buffer-reset
  22     buffer-length
  23     buffer-empty?
  24     buffer-capacity
  25     buffer@
  26 }
  27 "Reading from the buffer:"
  28 { $subsections
  29     buffer-peek
  30     buffer-pop
  31     buffer-read
  32     buffer-read-unsafe
  33     buffer-read-until
  34 }
  35 "Writing to the buffer:"
  36 { $subsections
  37     buffer-write1
  38     buffer-write
  39     buffer+
  40 } ;
  41
  42 ABOUT: "buffers"
  43
  44 HELP: buffer
  45 { $class-description "The class of I/O buffers, which resemble FIFO queues, but are optimized for holding bytes, are have underlying storage allocated at a fixed address. Buffers must be de-allocated manually. It has the following slots:"
  46     { $table
  47         { { $slot "size" } "The total size, in bytes, of the buffer" }
  48         { { $slot "ptr" } { "The " { $link c-ptr } " memory where data is stored" } }
  49         { { $slot "fill" } "The fill pointer, a write index where new data is added" }
  50         { { $slot "pos" } "The position, a read index where data is consumed" }
  51     }
  52 } ;
  53
  54 HELP: <buffer>
  55 { $values { "n" "a non-negative integer" } { "buffer" buffer } }
  56 { $description "Allocates a buffer with an initial capacity of " { $snippet "n" } " bytes." } ;
  57
  58 HELP: buffer-reset
  59 { $values { "n" "a non-negative integer" } { "buffer" buffer } }
  60 { $description "Resets the fill pointer to 0 and the position to " { $snippet "count" } "." } ;
  61
  62 HELP: buffer-consume
  63 { $values { "n" "a non-negative integer" } { "buffer" buffer } }
  64 { $description "Moves the position forward by " { $snippet "n" } " bytes. If it exceeds the fill pointer, both are reset to 0." } ;
  65
  66 HELP: buffer@
  67 { $values { "buffer" buffer } { "alien" alien } }
  68 { $description "Outputs the memory address of the current buffer position." } ;
  69
  70 HELP: buffer-end
  71 { $values { "buffer" buffer } { "alien" alien } }
  72 { $description "Outputs the memory address of the current fill-pointer." } ;
  73
  74 HELP: buffer-read
  75 { $values { "n" "a non-negative integer" } { "buffer" buffer } { "byte-array" byte-array } }
  76 { $description "Collects a byte array of " { $snippet "n" } " bytes starting from the buffer's current position, and advances the position accordingly. If there are less than " { $snippet "n" } " bytes available, the output is truncated." }
  77 { $examples
  78   { $example
  79     "USING: alien destructors io.buffers kernel prettyprint ;"
  80     "5 100 <buffer> [ B{ 7 14 21 } binary-object pick buffer-write buffer-read ] with-disposal ."
  81     "B{ 7 14 21 }"
  82   }
  83 } ;
  84
  85 HELP: buffer-length
  86 { $values { "buffer" buffer } { "n" "a non-negative integer" } }
  87 { $description "Outputs the number of unconsumed bytes in the buffer." }
  88 { $examples
  89   { $example
  90     "USING: alien destructors io.buffers kernel prettyprint ;"
  91     "100 <buffer> [ B{ 7 14 21 } binary-object pick buffer-write buffer-length ] with-disposal ."
  92     "3"
  93   }
  94 } ;
  95
  96 HELP: buffer-capacity
  97 { $values { "buffer" buffer } { "n" "a non-negative integer" } }
  98 { $description "Outputs the buffer's maximum capacity before growing." }
  99 { $examples
 100   { $example
 101     "USING: destructors io.buffers prettyprint ;"
 102     "100 <buffer> [ buffer-capacity ] with-disposal ."
 103     "100"
 104   }
 105 } ;
 106
 107 HELP: buffer-empty?
 108 { $values { "buffer" buffer } { "?" boolean } }
 109 { $description "Tests if the buffer contains no more data to be read or written." } ;
 110
 111 HELP: buffer-write
 112 { $values { "c-ptr" c-ptr } { "n" fixnum } { "buffer" buffer } }
 113 { $description "Copies a " { $link c-ptr } " to the buffer's fill pointer, and advances it accordingly." }
 114 { $warning "This word will corrupt memory if writing more than the space available in the buffer." } ;
 115
 116 HELP: buffer-write1
 117 { $values { "byte" "a byte" } { "buffer" buffer } }
 118 { $description "Appends a single byte to a buffer." }
 119 { $warning "This word will corrupt memory if the buffer is full." }
 120 { $examples
 121   { $example
 122     "USING: destructors io.buffers kernel prettyprint ;"
 123     "100 <buffer> [ 237 over buffer-write1 buffer-pop ] with-disposal ."
 124     "237"
 125   }
 126 } ;
 127
 128 HELP: buffer+
 129 { $values { "n" "a non-negative integer" } { "buffer" buffer } }
 130 { $description "Advances the fill pointer by " { $snippet "n" } " bytes." }
 131 { $warning "This word will leave the buffer in an invalid state if it does not have " { $snippet "n" } " bytes available." } ;
 132
 133 HELP: buffer-peek
 134 { $values { "buffer" buffer } { "byte" "a byte" } }
 135 { $description "Outputs the byte at the buffer position." } ;
 136
 137 HELP: buffer-pop
 138 { $values { "buffer" buffer } { "byte" "a byte" } }
 139 { $description "Outputs the byte at the buffer position and advances the position." } ;