[
https://issues.apache.org/jira/browse/TS-590?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12978048#action_12978048
]
Leif Hedstrom commented on TS-590:
----------------------------------
This is a beast of a change, but as per our mailing list discussions, I'm doing
the following:
0) If an API already returns TSReturnCode, leave it as is.
1) If an API can never fail, just leave it as is (but, make sure it doesn't
ever return some sort of "error" code).
2) If an API can only fail in a way where it's fatal, e.g. a call to xmalloc
"failing" and aborts, let it return whatever it should return (e.g. a pointer
to a new object). Basically, this API promises to return something useful, or
not return at all. This changes a few APIs, where they today can in theory
return error pointers (even though they typically never do since xmalloc etc.
follows this semantics)
3) If an API can fail, in many cases only in a debug build, change the return
value to be of TSReturnCode (TS_SUCCESS or TS_ERROR). The previous return value
is passed back into a handle provided in the API call.
> Change many SDK API signatures to be consistent
> -----------------------------------------------
>
> Key: TS-590
> URL: https://issues.apache.org/jira/browse/TS-590
> Project: Traffic Server
> Issue Type: Improvement
> Components: TSAPI
> Reporter: Leif Hedstrom
> Assignee: Leif Hedstrom
> Fix For: 2.1.6
>
>
> As has been discussed on the dev@ mailing list, we should clean up some of
> our APIs. I'm filing this bug here to track the discussion that has been had
> so far.
> The general consensus is that we'll stick to two types of signatures. The
> first one will presumably be the common one:
> 1) For any API that can fail (e.g. due to bad input, wrong types, or errors
> internally etc.), we'll stick to an interface of the form
> TSReturnCode TSSomeAPI(int in_param1, char *n_param2, int *out_param1,
> char **out_param2);
> we might want to consider adding some new error types to TSReturnCode as
> well, right now it's only error or success. One addition could be BAD_INPUT
> for example. But, we'll consistently use TSReturnCode only for indicating
> some sort of failures (i.e. no overloading of NULL pointers, -1, 0 etc. for a
> returned POD to mean failure).
> 2) For APIs that can not fail (quoting amc: "I promise to return something
> useful, or I will not return at all"), we allow the API to return a POD type.
> For Get() and Set() methods, we indicate this promise by dropping the Get()
> or Set() part of the name For example, TSMimeHdrLengthGet() becomes:
> int TSMimeHdrLength(TSMBuffer bufp, TSMLoc obj)
> This API can currently not fail in a release build, in debug builds, we
> should change such non-failing APIs to use ink_assert() on the sanity checks.
> The example above is particularly "bad" IMO, since it returns a length of -1
> to mean that the assert failed. In the implementation of this new version of
> the API, we'd have asserts like
> int
> TSMimeHdrLengthGet(TSMBuffer bufp, TSMLoc obj)
> {
> ink_assert(sdk_sanity_check_mbuffer(bufp) == TS_SUCCESS);
> ink_assert(sdk_sanity_check_mime_hdr_handle(obj) == TS_SUCCESS);
> ...
> We should make sure that we "group" similar APIs together properly, i.e. it
> makes no sense for dealing with (e.g.) TSMimeHdrFieldGet() as a can-fail API,
> and TSMimeHdrFieldFind() as one that can not fail.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
