Class MemoryBlob
An object that represents a memory blob, with various useful operations.
Methods
| MemoryBlob:Append (bytes) | Add bytes to the end of the blob. |
| MemoryBlob:Clone () | Create a clone of the blob. |
| MemoryBlob:GetBytes ([i1=1[, i2=#self]]) | Dump the blob's contents as a string of bytes. |
| MemoryBlob:GetProperties (out) |
Populate a table with the following blob properties:
|
| MemoryBlob:Insert (pos, bytes) | Insert bytes into the blob, starting at position pos. |
| MemoryBlob:IsLocked () | Indicates whether writes to this blob are restricted (via the native API). |
| MemoryBlob:Remove ([i1=1[, i2=#self]]) | Remove a range of bytes from the blob. |
| MemoryBlob:Submit () | (WIP, in probation) Submit this blob's contents to storage. |
| MemoryBlob:Sync (id) | (WIP, in probation) Synchronize this blob with an entry in storage, which then ceases to exist. |
| MemoryBlob:Write (pos, bytes) | Write bytes to the blob, starting at position pos, overwriting the blob's contents. |
Metamethods
| MemoryBlob:__len () | Metamethod. |
Methods
- MemoryBlob:Append (bytes)
-
Add bytes to the end of the blob.
This is a no-op for fixed-size and locked blobs.
Parameters:
- bytes Bytes Bytes to write.
Returns:
-
uint
Number of bytes actually written.
See also:
- MemoryBlob:Clone ()
-
Create a clone of the blob.
The clone inherits the alignment, resizability, size, and type of the original blob.
Initially, the clone will contain a copy of the parent's current contents. The two blobs are independent, however; changes to one's contents are not reflected in the other.
Clones begin unlocked.
Returns:
-
MemoryBlob
Cloned blob.
- MemoryBlob:GetBytes ([i1=1[, i2=#self]])
-
Dump the blob's contents as a string of bytes.
If either index refers to a position outside the blob, or i1 > i2 (after normalizing any negative indices), an empty string is returned.
Parameters:
- i1 uint Index of first byte. If negative, the index counts down from the end of the blob, much like certain Lua string functions. (default 1)
- i2 uint Index of last byte. Again, indices may be negative. (default #self)
Returns:
-
string
Copy of current blob contents.
See also:
- MemoryBlob:GetProperties (out)
-
Populate a table with the following blob properties:
- alignment: As per New, an integer ≥ 0, with 0 meaning default alignment.
- resizable: As per New, a boolean indicating resizability.
Parameters:
- out optional table Table to populate and return. If absent, a fresh table is created.
Returns:
-
table
Properties table.
- MemoryBlob:Insert (pos, bytes)
-
Insert bytes into the blob, starting at position pos.
The current contents from pos onward are moved ahead #bytes positions to make room. In the case of fixed-size blobs, any bytes moved beyond the end of the blob are thrown away.
This is a no-op for locked blobs.
Parameters:
- pos
int
Insert position, between 1 and #self, inclusive. A negative index may also be provided,
cf. MemoryBlob:GetBytes for details.
Resizable blobs may also use position #self + 1, with behavior like
self:Append(bytes).No bytes are inserted when the position lies outside the legal range.
- bytes Bytes Bytes to insert.
Returns:
-
uint
Number of bytes actually inserted.
See also:
- pos
int
Insert position, between 1 and #self, inclusive. A negative index may also be provided,
cf. MemoryBlob:GetBytes for details.
- MemoryBlob:IsLocked ()
-
Indicates whether writes to this blob are restricted (via the native API).
Certain MemoryBlob methods will early-out when given a locked blob, cf. various summaries.
Returns:
-
boolean
The blob is locked?
- MemoryBlob:Remove ([i1=1[, i2=#self]])
-
Remove a range of bytes from the blob.
Any bytes beyond i2 will be moved down to fill the vacated positions.
Naturally, resizable blobs will shrink. Since fixed-size blobs cannot do this, there will be i2 - i1 + 1 "extra" bytes at the end, after elements move down; these will be left as-is.
This is a no-op for locked blobs.
Parameters:
- i1 int Index of first byte to remove, cf. MemoryBlob:GetBytes. (default 1)
- i2 int Index of last byte to remove, ditto. (default #self)
Returns:
-
uint
Number of bytes actually removed.
See also:
- MemoryBlob:Submit ()
-
(WIP, in probation) Submit this blob's contents to storage. This is a mechanism geared toward
sharing memory among Lua processes,
which can even be done without copying when certain conditions are met (cf. MemoryBlob:Sync for details,
as well as the comments about resizable blobs that follow).
Essentially, an empty resizable blob with the same alignment is first created in storage.
If the original blob is resizable, its contents are swapped directly into the stored entry.
Fixed-size blobs cannot do this, so something like
entry:Append(fixed\_blob)is done instead.To keep memory under control, any blobs in storage left unsynchronized will be evicted after a few frames have gone by (on average, 5). Listeners for "stale_entry" will be sent a message each time this happens (cf. GetBlobDispatcher), with an id field containing the former entry's ID.
This is a no-op for locked, resizable blobs.
Returns:
-
string or nil
On success, an ID for later use by MemoryBlob:Sync. Otherwise, nil.
See also:
- MemoryBlob:Sync (id)
-
(WIP, in probation) Synchronize this blob with an entry in storage, which then ceases to exist.
For fixed-size blobs, this is essentially
self:Write(1, bytes), with bytes being the entry's contents.With resizable blobs, the same is true, but the blob's length is also trimmed to #bytes, if necessary. When the blob and stored entry have a common alignment (cf. MemoryBlob:Submit), the blob simply assumes ownership of the latter's contents, forgoing a potentially expensive copy.
This operation is designed for safe communication between Lua processes.
This is a no-op for locked blobs, or if id does not refer to a valid entry.
Parameters:
- id string Stored entry's lookup ID, cf. MemoryBlob:Submit.
Returns:
-
boolean
Synchronization succeeded?
See also:
- MemoryBlob:Write (pos, bytes)
-
Write bytes to the blob, starting at position pos, overwriting the blob's contents.
Resizable blobs will grow to accommodate these bytes, if necessary, whereas writes to fixed-size blobs will stop if they reach the end.
This is a no-op for locked blobs.
Parameters:
- pos
int
Write position, between 1 and #self, inclusive. A negative index may also be provided,
cf. MemoryBlob:GetBytes for details.
Resizable blobs may also use position #self + 1, with behavior like
self:Append(bytes).No bytes are written when the position lies outside the legal range.
- bytes Bytes Bytes to write.
Returns:
-
uint
Number of bytes actually written.
See also:
- pos
int
Write position, between 1 and #self, inclusive. A negative index may also be provided,
cf. MemoryBlob:GetBytes for details.