[Format] Clarify calling get_next after error in C stream interface
- Dominant language
- C++
- Stars
- 17.1k
- Forks
- 4.3k
- Avg merge
- 3d 13h
- Merged PRs (30d)
- 88
Description
### Describe the enhancement requested
This was asked about in https://github.com/apache/arrow-adbc/issues/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
Contributor guide
Assessment
This issue has not been assessed yet.