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
Fix For: 2.1.5
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.
