Mutable Blobs

[DonaldHays]

For writing to binary files or network protocols, it would be nice to have a mutable version of Blob, with APIs like setU16, setF32, etc.

Blob is currently an immutable type. There are significant advantages to immutable types: they are easy to reason about, and are thread safe. However, those traits bring a wrinkle: I'm sure plenty of Lovr code assumes and relies upon the immutability of Blob, so mutability APIs cannot simply be bolted onto the existing type without risking copious bugs.

Node.js has Buffer and Blob types. A Blob is immutable, much like Lovr's, while a Buffer is mutable. It's possible to create Blobs from Buffers, and vice-versa.

Apple's Foundation framework has NSMutableData and NSData. This setup is a little clever: NSMutableData is a subclass of NSData, so you can pass NSMutableData to any API that expects an NSData, but not the other way around. This introduces the risk of data being unexpectedly mutated while being held by something that expects it to be immutable. To address this, both classes implement copy and mutableCopy methods. Both classes implement mutableCopy by returning a new NSMutableData. But they diverge for implementing copy: NSMutableData creates a new NSData, but NSData implements copy by merely returning self. Since NSData is immutable, this is safe, because—memory management considerations aside—a copy of an NSData would be semantically identical. APIs that take an NSData, then, follow a simple pattern: always call copy on the incoming instance; if you got an NSData, it's effectively a no-op, while an NSMutableData will give you an actual new NSData copy.

Another option could be to add mutable APIs to Blob, but also introduce a Blob:freeze() method, wherein it would be an error to call a mutable API on a Blob after calling freeze. Calling freeze on a frozen instance does nothing, allowing it to be called repeatedly. APIs, by convention, would generally immediately call freeze on any Blob instances they receive, unless they explicitly are intended to handle mutable Blobs. Programmers would be expected to understand that their Blobs will freeze if not already frozen after calling most APIs. Or, there could also be a Blob:asFrozen() method, which returns self if the instance is already frozen, or, if not, creates a new Blob, freezes it, and returns that.

[bjornbytes]

Blobs are actually mutable, Blob:getPointer returns a pointer you can modify with FFI. There is a pattern in place where you can create an Image or Sound, get its blob, get the pointer, and write directly to the resource with FFI. It's more of an advanced feature though.

There are probably some other areas that wouldn't work properly if their blobs were modified though. Like, you might be able to crash the framework if you modified a ModelData/Rasterizer blob in just the right way.

Also, love2d has a design similar to NSMutableData: They have Data and ByteData classes. Data is a superclass of Image, Sound, Rasterizer, as well as ByteData, and has the :get methods. ByteData is a custom object you can create from Lua that has the :set methods (as well as the :get methods since it's a subclass of Data). However, Data also has a :getPointer method, so you can technically mutate the "immutable" Data class if you really want to.

So, I don't think right now there is a hard rule that Blobs must be immutable, and there could probably be :set* versions of all the existing :get* methods. We could add a mutable version of Blob like love/NS, but I'm not really sure what the benefit would be? There is a little bit of extra safety which prevents modification of blobs that someone else is using I guess.

Tangentially, another thing I've thought about is trying to bring the Buffer format code into Blob/lovr.data somehow. That way you could use the same system to write to both GPU data in buffers and CPU data in Blobs.

[bjornbytes]

(I should add that I don't think love's ByteData was added for mutability vs. immutability reasons, I think they just needed a concrete subclass of Data so that other methods in love.data could return binary data).

[bjornbytes]

Here is a quick branch that implements Blob setters

[DonaldHays]

Oh, I didn't realize the pointer was mutable all along. If it's already technically mutable, I suppose it wouldn't be a material change to just add the setter APIs.

Yeah, the benefit of immutable types is just knowing that once you receive one, you know its contents will never change. You can hold onto it for a long time, and any invariants established in the first inspection will always hold true. Multiple threads can share references to the same object and read from it without locks at the same time and know that nobody will be changing it out from under them.

Without immutable types, it's just up to the users to make sure they never mutate a value if another party is expecting it not to change.

Tangentially, another thing I've thought about is trying to bring the Buffer format code into Blob/lovr.data somehow. That way you could use the same system to write to both GPU data in buffers and CPU data in Blobs.

Ooooh, that would be fantastic. Having a format description would let you write an entire table as binary data in one shot, fewer hoops to jump through.

Here is a quick branch that implements Blob setters

For what it's worth, I did a code review on this commit and it looks good to me!

Admittedly, it took a bit for me to do the review, because I've only touched Lua's C API a little and I had to learn exactly what some of the functions did. But still! It looks like it does what it's supposed to, and they're exactly the methods I would like to have.

[DonaldHays]

Tangentially, another thing I've thought about is trying to bring the Buffer format code into Blob/lovr.data somehow. That way you could use the same system to write to both GPU data in buffers and CPU data in Blobs.

Random idea: "structs" that combine blobs and buffer formats. You create a Struct by giving it a Blob and a format, then it uses metatable magic to expose dynamic properties that just read from or write to the blob according to the format. It would be an error to attempt to dynamically add additional properties, or assign a value having the incorrect type to a property. But the tradeoff is that it gives you memory layout guarantees, they may be more cache friendly, and you can readily submit a Struct to the GPU or write it out to disk.

In many ways it's like userdata-backed APIs, except allowing format to be dictated from LUA code.

[bjornbytes]

This would be convenient, but I'd be worried about garbage. If I write something like lights[i].position.x = 0, wouldn't each "dot" in that expression need to run an __index metamethod and returns a new table?

In my head I was vaguely thinking something similar to Buffer, just for Blobs on the CPU:

blob = lovr.data.newBlob(...)

format = { -- Not sure if this needs to be a userdata object or not
  { 'position', 'vec3' },
  { 'color', 'vec4' },
  { 'type', 'u32' }
}

blob:setData(format, {
  { position = { 1, 2, 3 }, color = { 1, 1, 1, 1 }, type = types.POINT },
  { position = { 1, 2, 3 }, color = { 1, 0, 1, 1 }, type = types.SPOT },
})

But Buffer/Blob would share the code for the implementation. Some downsides are:

• The code for those recursive buffer formats is super complicated! It feels like a liability.
• Some of the buffer format stuff feels GPU-specific (matrices, mostly). That's probably fine.

Another idea is to add something like Lua 5.3's binary packing API. LÖVE has this exposed as love.data.pack and love.data.unpack. LÖVR could add this too if someone needs it. I'm not sure how convenient it is to pack big structs though.

[bjornbytes]

I merged the blob-setters branch, so now those Blob:setI8/U8/I16/U16/I32/U32/F32/F64 methods exist!