Buffers¶
Support for buffers - regions of memory without a particular interpretation.
This module provides bytes and buffer types which
can be used to manage memory regions.
A bytes is a contiguous memory region - really a data structure
containing a pointer, length, and also the information necessary to free the
memory region when it is no longer used.
A buffer consists of a sequence views into bytes
objects. A bytes object might be shared by several
buffer objects.
These types should be safe to use in a multi-locale context. These types should free their memory after the last user of that memory goes out of scope. They are currently reference counted but that may not always be the case.
-
record
bytes¶ This type represents a contiguous sequence of bytes. This sequence of bytes is represented with a C pointer and length and is currently reference counted. Note that this record contains private fields in addition to the home field.
-
var
home: locale¶ The home locale storing the data
-
var
-
proc
bytes.bytes()¶ Construct an empty bytes object
-
proc
bytes.bytes(len: int(64), out error: syserr) Construct a bytes object by allocating zero-filled memory.
Arguments: - len -- the number of bytes to allocate
- error -- (optional) capture an error that was encountered instead of halting on error
-
record
buffer_iterator¶ This type represents a particular location with a buffer. Use buffer methods like
buffer.startandbuffer.advanceto create and manipulatebuffer_iterators. Note that this record contains private fields in addition to the home field.-
var
home: locale¶ The home locale storing the data
-
var
-
record
buffer_range¶ A region within a buffer (indicated by two
buffer_iterators )-
var
start: buffer_iterator¶
-
var
end: buffer_iterator¶
-
var
-
proc
buffer_range.len: int(64)¶ Returns: the number of bytes stored in a buffer_range
-
record
buffer¶ A buffer which can contain multiple memory regions (that is, multiple regions of
bytesobjects). Note that this record contains private fields in addition to the home field.-
var
home: locale¶ The home locale storing the data
-
var
-
proc
buffer.buffer(out error: syserr)¶ Create an empty buffer.
Arguments: error -- (optional) capture an error that was encountered instead of halting on error
-
proc
buffer.flatten(range: buffer_range, out error: syserr)¶ Flatten a buffer. Create a new
bytesobject and copy the buffer into it. This function should work even if buffer is remote.Arguments: - range -- the region of the buffer to copy, for example buffer.all()
- error -- (optional) capture an error that was encountered instead of halting on error
Returns: a newly constructed bytes object on the current locale
-
proc
buffer.append(b: bytes, skip_bytes: int(64) = 0, len_bytes: int(64) = b.len, out error: syserr)¶ Append a
bytesobject to abuffer. This function might store the passed bytes object by reference instead of copying it. The current implementation will always do so and will always increase the reference count of the bytes object. The version of this function called without the error argument will halt if an error is encountered.Arguments: - b -- the
bytesobject to append - skip_bytes -- how many bytes at the front of b to skip
- len_bytes -- how many bytes to append to the buffer
- error -- (optional) capture an error that was encountered instead of halting on error
- b -- the
-
proc
buffer.append(buf: buffer, part: buffer_range = AppendExpr.Call08, out error: syserr) Append a
bufferobject to abuffer. This function might store a pointers to the bytes objects contained in buf instead of copying them. If that happens, the current implementation will increase their reference counts. The version of this function called without the error argument will halt if an error is encountered.Arguments: - buf -- the
bufferobject to append - part -- a
buffer_rangeindicating which section of the buffer to copy. Defaults to all of the buffer. - error -- (optional) capture an error that was encountered instead of halting on error
- buf -- the
-
proc
buffer.prepend(b: bytes, skip_bytes: int(64) = 0, len_bytes: int(64) = b.len, out error: syserr)¶ Prepend a
bytesobject to abuffer. This function might store the passed bytes object by reference instead of copying it. The current implementation will always do so and will always increase the reference count of the bytes object. The version of this function called without the error argument will halt if an error is encountered.Arguments: - b -- the
bytesobject to prepend - skip_bytes -- how many bytes at the front of b to skip
- len_bytes -- how many bytes to append to the buffer
- error -- (optional) capture an error that was encountered instead of halting on error
- b -- the
-
proc
buffer.start(): buffer_iterator¶ Returns: a buffer_iteratorto the start of a buffer
-
proc
buffer.end(): buffer_iterator¶ Returns: a buffer_iteratorto the end of a buffer
-
proc
buffer.all(): buffer_range¶ Returns: a buffer_rangefor the entirety of a buffer
-
proc
buffer.next_part(ref it: buffer_iterator)¶ Advance a
buffer_iteratorto the next contigous memory region stored thereinArguments: it -- the buffer iterator to advance
-
proc
buffer.prev_part(ref it: buffer_iterator)¶ Advance a
buffer_iteratorto the previous contigous memory region stored thereinArguments: it -- the buffer iterator to advance
-
proc
buffer.advance(ref it: buffer_iterator, amount: int(64))¶ Advance a
buffer_iteratorby a particular number of bytes.Arguments: - it -- the buffer iterator to advance
- amount -- the number of bytes to advance
-
proc
buffer.copyout(it: buffer_iterator, out value, out error: syserr): buffer_iterator¶ Read a basic type from a buffer. This method reads the value by copying from memory - so it reads a binary value in native endianness.
Arguments: - it -- a
buffer_iteratorwhere reading will start - value -- a basic type (integral or floating point value)
- error -- (optional) capture an error that was encountered instead of halting on error
Returns: a buffer iterator storing the position immediately after the read value.
- it -- a
-
proc
buffer.copyin(it: buffer_iterator, value, out error: syserr): buffer_iterator¶ Write a basic type to a buffer. This method writes the value by copying to memory - so it reads a binary value in native endianness.
Arguments: - it -- a
buffer_iteratorwhere reading will start - value -- a basic type (integral or floating point value)
- error -- (optional) capture an error that was encountered instead of halting on error
Returns: a buffer iterator storing the position immediately after the written value.
- it -- a