Buffer:-query unexpectedly causes Buffer instance vars to be updated

[mtmccrea]

Update

The issue subsequently was clarified, see below.
In short, a side affect of calling -query is that Buffer's lang-side instance variables are updated, which was not the intention of the original implementation.

If/when this is resolved, various warnings and clarifications added by this PR can be removed or updated.

Steps to reproduce

The behavior is observable using the code snippet in Buffer:-alloc help doc:

s.boot;
b = Buffer.new(s, 44100 * 8.0, 2);
b.query; // numFrames = 0
b.alloc;
b.query; // numFrames = 352800
b.free;

Expected vs. actual behavior

Buffer should be allocated (fails in 3.13), the the state should be accurately returned when queried (not sure what the full query results should be for an nonallocated buffer).
It seems that either the buffer isn't allocated (3.12.2), the state isn't properly set, and/or query is returning erroneous results.

SC 3.12.2 release

b = Buffer.new(s, 44100 * 8.0, 2);
-> Buffer(0, 352800.0, 2, 48000.0, nil)

b.query; // numFrames = 0
-> Buffer(0, 352800.0, 2, 48000.0, nil)
    bufnum: 0
    numFrames: 0
    numChannels: 0
    sampleRate: 0.0

b.alloc;
-> Buffer(0, 0, 0, 0.0, nil) // failed silently?

b.query; // numFrames = 352800
-> Buffer(0, 0, 0, 0.0, nil) // no change in state, not allocated
    bufnum: 0
    numFrames: 0
    numChannels: 0
    sampleRate: 0.0

SC 3.13 release

b = Buffer.new(s, 44100 * 8.0, 2);
-> Buffer(0, 352800.0, 2, 48000.0, nil)

b.query; // numFrames = 0
-> Buffer(0, 352800.0, 2, 48000.0, nil)
    bufnum: 0
    numFrames: 0
    numChannels: 0
    sampleRate: 0.0 

b.alloc;
-> Buffer(0, 0, 0, 0.0, nil)
    /b_alloc: memory allocation failed

I don't have time to dig deeper into the issue atm, but the problem seems specific to the instance method because Buffer:*alloc appears to be working fine:

b = Buffer.alloc(s, s.sampleRate * 8.0, 2);
-> Buffer(3, 352800.0, 2, 48000.0, nil)

b.query
-> Buffer(3, 352800.0, 2, 48000.0, nil)
    bufnum: 3
    numFrames: 352800
    numChannels: 2
    sampleRate: 48000.0

[jamshark70]

Deleted one message bc it was wrong.

Buffer.new does not allocate in the server, so there is nothing to query in the server.

In general, Buffer.new should not be used because it results in a language-side object with no server-side referent. Buffer.alloc is the standard way.

So I think the help example needs to be updated.

[mtmccrea]

I agree Buffer.alloc is the standard way and is preferred in 95% of cases. There are still cases to instantiate the object without a corresponding server-side object, even though it's error prone and needs to be done carefully.

For example, Plot uses this for it's completion action to have access to some of the metadata for it's configuration (this is how I came across the issue). Not saying it's the best way, but it does get use.

So I think the help example needs to be updated.

I made some related updates to docs in this PR that explains some of the gotchas related to the the mirrored lang/server objects and Buffer:-query. But yes, the alloc method doc needs updating as well.

[mtmccrea]

Revisiting this after working on the PR linked above makes me realize why this breaks...

b = Buffer.new(s, 44100 * 8.0, 2);
-> Buffer(0, 352800.0, 2, 48000.0, nil) // lang-side state

A call to query updates instance vars of the Buffer object to reflect server-side state.

b.query; 
-> Buffer(0, 352800.0, 2, 48000.0, nil)
    bufnum: 0
    numFrames: 0
    numChannels: 0
    sampleRate: 0.0

so following this with a call to alloc fails, either silently or with a warning depending on the SC version, because it's trying to instantiate a buffer now with 0 frames, 0 channels, etc.

This is an unintended side-affect of the action of the OSC responders stored in buffer's entry in the serverCaches responding to query's info request. I noted this in the doc update of that PR, but should be fixed in the long term.

[jamshark70]

A call to query updates instance vars of the Buffer object to reflect server-side state.

I realized this later -- good catch.

But: Why would one set up a Buffer object with new and a desired size, and then query it, if you know that there's nothing on the server to query? I think it's just that the help example is old (predates the current query behavior) and demonstrates a bad pattern that nobody would ever have serious reason to do. Hence, probably just delete it.

[mtmccrea]

Why would one set up a Buffer object with new and a desired size, and then query it, if you know that there's nothing on the server to query?

Before this side effect was introduced, it would have been an illustrative example, but now... not so much. I'll remove it as part of the related PR I linked above.

I'll update the name to reflect the new understanding of the problem: Buffer:-query has a side effect of updating the lang-side object's vars, despite the original implementation intending to only post the server-side state and leave the lang-side object untouched.