[jira] Updated: (TS-590) Change many SDK API signatures to be consistent

["Leif Hedstrom (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/TS-590?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Leif Hedstrom updated TS-590:
-----------------------------

    Attachment: API.diff

First cut at changed API interfaces.


> 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