jyapayne/nim-faststreams
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix the CI; Improve docs

Browse source
This commit is contained in:
Zahary Karadjov 2022-01-22 20:01:20 +02:00
commit 37a183153c
No known key found for this signature in database
GPG key ID: C8936F8A3073D609
3 changed files with 11 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

16
faststreams/outputs.nim
View file

@ -492,19 +492,23 @@ proc getWritableBytesOnANewPage(s: OutputStream, spanSize: Natural): ptr byte =
template getWritableBytes*(sp: OutputStream, spanSizeParam: Natural): openArray[byte] =
## Returns a contiguous range of memory that the caller is free to populate fully
## or partially. The caller indicates how many bytes were written to the span by
## calling `advance(numberOfBytes)` once or multiple times. Advancing the stream
## past the allocated span size is considered a defect. The typical usage pattern
## of this API looks as follows:
## or partially. The caller indicates how many bytes were written to the openArray
## by calling `advance(numberOfBytes)` once or multiple times. Advancing the stream
## past the allocated size is considered a defect. The typical usage pattern of this
## API looks as follows:
##
## stream.advance(myComponent.writeBlock(stream.getWritableBytes(maxBlockSize)))
##
## In the example, `writeBlock` would be a function returning the number of bytes
## written to the span.
## written to the openArray.
##
## While it's not illegal to issue other writing operations to the stream during
## the `getWritetableSpan` -> `advance` sequence, doing this is not recommended
## the `getWritetableBytes` -> `advance` sequence, doing this is not recommended
## because it will result in overwriting the same range of bytes.
##
## One limitation of this API is that the returned `openArray` will be considered
## read-only by Nim. You may need to use `unsafeAddr` in your writing functions
## to get around this limitation.
let
s = sp
spanSize = spanSizeParam