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]&gt;
发件时间:2026年9月29日 18:04
收件人:dev <[email protected]&gt;
主题:[DISCUSS] C API compatibility and error-code return conventions



       Hi&nbsp;everyone,


While&nbsp;working&nbsp;on&nbsp;PR&nbsp;#970,&nbsp;we&nbsp;need&nbsp;to&nbsp;clarify&nbsp;the&nbsp;direction&nbsp;of&nbsp;error&nbsp;handling&nbsp;in&nbsp;the&nbsp;C&nbsp;API.


There&nbsp;are&nbsp;two&nbsp;main&nbsp;questions:


1.&nbsp;For&nbsp;existing&nbsp;APIs&nbsp;that&nbsp;cannot&nbsp;return&nbsp;error&nbsp;codes,&nbsp;should&nbsp;we&nbsp;modify&nbsp;them&nbsp;directly,&nbsp;or&nbsp;keep&nbsp;the&nbsp;old&nbsp;APIs&nbsp;and&nbsp;add&nbsp;new&nbsp;error-reporting&nbsp;versions?&nbsp;The&nbsp;first&nbsp;option&nbsp;breaks&nbsp;compatibility,&nbsp;while&nbsp;the&nbsp;second&nbsp;requires&nbsp;maintaining&nbsp;two&nbsp;API&nbsp;sets.


2.&nbsp;C++&nbsp;internal&nbsp;APIs&nbsp;generally&nbsp;use:


&nbsp;&nbsp;&nbsp;&nbsp;ERRNO&nbsp;func(...,&nbsp;result);


The&nbsp;current&nbsp;C&nbsp;APIs&nbsp;more&nbsp;often&nbsp;use:


&nbsp;&nbsp;&nbsp;&nbsp;result&nbsp;func(...,&nbsp;ERRNO*);


For&nbsp;pointer-returning&nbsp;C&nbsp;APIs,&nbsp;`nullptr`&nbsp;can&nbsp;indicate&nbsp;that&nbsp;no&nbsp;object&nbsp;was&nbsp;returned,&nbsp;while&nbsp;`ERRNO*`&nbsp;provides&nbsp;the&nbsp;specific&nbsp;error.&nbsp;Should&nbsp;we&nbsp;standardize&nbsp;on&nbsp;the&nbsp;C++&nbsp;style&nbsp;of&nbsp;“error&nbsp;code&nbsp;as&nbsp;the&nbsp;return&nbsp;value&nbsp;plus&nbsp;output&nbsp;parameters,”&nbsp;or&nbsp;keep&nbsp;the&nbsp;current&nbsp;C&nbsp;style&nbsp;and&nbsp;define&nbsp;clear&nbsp;rules&nbsp;for&nbsp;how&nbsp;the&nbsp;return&nbsp;pointer&nbsp;and&nbsp;error&nbsp;code&nbsp;should&nbsp;be&nbsp;used?


It&nbsp;would&nbsp;be&nbsp;good&nbsp;to&nbsp;agree&nbsp;on&nbsp;these&nbsp;two&nbsp;points&nbsp;before&nbsp;deciding&nbsp;whether&nbsp;PR&nbsp;#970&nbsp;should&nbsp;modify&nbsp;the&nbsp;existing&nbsp;APIs&nbsp;or&nbsp;introduce&nbsp;new&nbsp;error-reporting&nbsp;APIs.


Best,
Colin

Reply via email to