[
https://issues.apache.org/jira/browse/TS-590?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Leif Hedstrom resolved TS-590.
------------------------------
Resolution: Fixed
> 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: TS API
> Reporter: Leif Hedstrom
> Assignee: Leif Hedstrom
> Priority: Critical
> Fix For: 2.1.6
>
> Attachments: API.diff
>
>
> 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.
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
