apache / apache/arrow

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

Open
#48,698 1 comment 0 reactions 0 assignees View on GitHub
Component: Format Type: enhancement
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.