Hi Colin,
My preference is: 1. Keep released APIs and add error-reporting variants. The old APIs can wrap the new implementation to reduce maintenance costs. Unreleased APIs can be changed directly. 2. Prefer ERRNO func(..., out_result) for new APIs so callers can check errors consistently. Existing result func(..., ERRNO*) APIs can remain, provided they always set the error code, including on success, and clearly distinguish empty results, normal end-of-iteration, and failures. For #970, I support adding error-reporting APIs and migrating the relevant callers while preserving compatibility for released APIs. Best, Hongzhi Hongzhi Gao [email protected] 原始邮件 发件人:ColinLee <[email protected]> 发件时间:2026年9月29日 18:04 收件人:dev <[email protected]> 主题:[DISCUSS] C API compatibility and error-code return conventions Hi everyone, While working on PR #970, we need to clarify the direction of error handling in the C API. There are two main questions: 1. For existing APIs that cannot return error codes, should we modify them directly, or keep the old APIs and add new error-reporting versions? The first option breaks compatibility, while the second requires maintaining two API sets. 2. C++ internal APIs generally use: ERRNO func(..., result); The current C APIs more often use: result func(..., ERRNO*); For pointer-returning C APIs, `nullptr` can indicate that no object was returned, while `ERRNO*` provides the specific error. Should we standardize on the C++ style of “error code as the return value plus output parameters,” or keep the current C style and define clear rules for how the return pointer and error code should be used? It would be good to agree on these two points before deciding whether PR #970 should modify the existing APIs or introduce new error-reporting APIs. Best, Colin
