1 USING: alien byte-arrays destructors help.markup help.syntax
5 ARTICLE: "buffers" "Locked I/O buffers"
6 "I/O buffers are first-in-first-out queues of bytes."
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."
10 "Buffers are used to implement native I/O backends."
12 "Buffer words are found in the " { $vocab-link "io.buffers" } " vocabulary."
17 "Buffers must be manually deallocated by calling " { $link dispose } "."
27 "Reading from the buffer:"
35 "Writing to the 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:"
47 { "size" "The total size, in bytes, of the buffer" }
48 { "ptr" { "The " { $link c-ptr } " memory where data is stored" } }
49 { "fill" "The fill pointer, a write index where new data is added" }
50 { "pos" "The position, a read index where data is consumed" }
55 { $values { "n" "a non-negative integer" } { "buffer" buffer } }
56 { $description "Allocates a buffer with an initial capacity of " { $snippet "n" } " bytes." } ;
59 { $values { "n" "a non-negative integer" } { "buffer" buffer } }
60 { $description "Resets the fill pointer to 0 and the position to " { $snippet "count" } "." } ;
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." } ;
67 { $values { "buffer" buffer } { "alien" alien } }
68 { $description "Outputs the memory address of the current buffer position." } ;
71 { $values { "buffer" buffer } { "alien" alien } }
72 { $description "Outputs the memory address of the current fill-pointer." } ;
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." }
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 ."
86 { $values { "buffer" buffer } { "n" "a non-negative integer" } }
87 { $description "Outputs the number of unconsumed bytes in the buffer." }
90 "USING: alien destructors io.buffers kernel prettyprint ;"
91 "100 <buffer> [ B{ 7 14 21 } binary-object pick buffer-write buffer-length ] with-disposal ."
97 { $values { "buffer" buffer } { "n" "a non-negative integer" } }
98 { $description "Outputs the buffer's maximum capacity before growing." }
101 "USING: destructors io.buffers prettyprint ;"
102 "100 <buffer> [ buffer-capacity ] with-disposal ."
108 { $values { "buffer" buffer } { "?" boolean } }
109 { $description "Tests if the buffer contains no more data to be read or written." } ;
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." } ;
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." }
122 "USING: destructors io.buffers kernel prettyprint ;"
123 "100 <buffer> [ 237 over buffer-write1 buffer-pop ] with-disposal ."
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." } ;
134 { $values { "buffer" buffer } { "byte" "a byte" } }
135 { $description "Outputs the byte at the buffer position." } ;
138 { $values { "buffer" buffer } { "byte" "a byte" } }
139 { $description "Outputs the byte at the buffer position and advances the position." } ;