TS-995: IP support renaming

["Alan M. Carroll" <am...@network-geographics.com>]

Part of the ongoing efforts is to remove the archaic "ink_" prefixes. I would like to do this for the IP support, essentially ink_inet.h immediately after the 3.1.2 release. I propose that we use the prefixes ts_ip_, ts_ip4_, ts_ip6_ for functions, except for property checks which for readability would put "is" or "has" before the "ip".

ts_ip4_set(...); ///< Set to IPv4 address.
ts_ip4_cast(...); ///< Cast to sockaddr_in
ts_ip4_addr_cast(...); ///< Cast to in_addr_t member.
ts_ip_copy(lhs, rhs); ///< Copy IP address.

ts_is_ip(...); ///< Check for an IP address family.
ts_is_ip6(...); ///< Check for being IPv6 address.
ts_is_ip_loopback(...); ///< Check for IP loopback address.

For types the "TsIp" prefix would be used, to conform to the coding style guide. So

TsIpEndpoint /// A sockaddr equivalent, contains the full IP endpoint data.
TsIpAddr /// An IP address, nothing else.
in_port_t /// Standard definition for IP port. Typedef to TsIpPort?

As a side note, since this came up recently, I have found that having both TsIpEndpoint and TsIPAddr quite useful. It can become confusing about whether the TsIpEndpoint port value is relevant. Sometimes it is the other case, where the port matters but the address does not. This is made clear if it is always relevant, and if the API would prefer it to not be, then TsIpAddr can be used. TsIpAddr is also useful in places where there are a large number of instances and the reduced memory footprint is signficant (e.g., HostDB).

We might also want to adopt the convention that functions using the lexeme "addr" mean TsIpAddr, and "ip" TsIpEndpoint to further reduce confusion. Unfortunately, this conflicts with the InkAPI. However, that duality was primarily an expedient for the transition and for 4.0 all of the old style IPv4 functions will be removed and we can fix it at that point.

Re: TS-995: IP support renaming

[Leif Hedstrom <zw...@apache.org>]

On Jan 28, 2012, at 10:32 AM, "Alan M. Carroll" <am...@network-geographics.com> wrote:

> Part of the ongoing efforts is to remove the archaic "ink_" prefixes. I would like to do this for the IP support, essentially ink_inet.h immediately after the 3.1.2 release. I propose that we use the prefixes ts_ip_, ts_ip4_, ts_ip6_ for functions, except for property checks which for readability would put "is" or "has" before the "ip".
> 
> ts_ip4_set(...); ///< Set to IPv4 address.
> ts_ip4_cast(...); ///< Cast to sockaddr_in
> ts_ip4_addr_cast(...); ///< Cast to in_addr_t member.
> ts_ip_copy(lhs, rhs); ///< Copy IP address.
> 
> ts_is_ip(...); ///< Check for an IP address family.
> ts_is_ip6(...); ///< Check for being IPv6 address.
> ts_is_ip_loopback(...); ///< Check for IP loopback address.
> 
> For types the "TsIp" prefix would be used, to conform to the coding style guide. So
> 
> TsIpEndpoint /// A sockaddr equivalent, contains the full IP endpoint data.
> TsIpAddr /// An IP address, nothing else.
> in_port_t /// Standard definition for IP port. Typedef to TsIpPort?

Sounds good.

> 
> As a side note, since this came up 
> 
> We might also want to adopt the convention that functions using the lexeme "addr" mean TsIpAddr, and "ip" TsIpEndpoint to further reduce confusion. Unfortunately, this conflicts with the InkAPI. However, that duality was primarily an expedient for the transition and for 4.0 all of the old style IPv4 functions will be removed and we can fix it at that point.
> 

Yeah, we did promise not to break APIs within e.g. 3.x.

-- Leif