[Format] Clarify calling get_next after error in C stream interface

[amoeba]

Describe the enhancement requested

This was asked about in apache/arrow-adbc#3827 and I thought filing an issue here would be good.

Should it be explicitly stated that a stream is in either an undefined or invalid state after get_next returns an error?

Reading the docstrings and docs, I think it could be more clear. The question in the linked issue was whether it's considered valid to essentially smuggle a non-fatal error into a stream and continue processing. I'm not sure if this was an intended use case.

We could update the docs and docstrings to say one or two related things:

1. get_next() MUST not be called if calling it previously on the current stream returned a non-zero value (an error).
2. After calling get_next() on an ArrowArrayStream returns a non-zero value, the only value valid callbacks which may be called are get_last_error() and release().

Do others think the clarification is useful? If so, I could file a PR here to get the language right and then propagate the change to other repos where we the ArrowArrayStream definition is duplicated/vendored.

Component(s)

Format

[goldigd05]

Hi, I am interested in this documentation enhancement.

I agree that clarifying the valid state of ArrowArrayStream after get_next()
returns an error would help developers avoid using a stream in an invalid state.
I would be happy to file a PR updating the docstrings and propagating the
clarification to other repos where the ArrowArrayStream definition is duplicated.