#use wml::ossp area=pkg:lib subarea=sa
OSSP sa
Socket Abstraction
Abstract
OSSP sa is an abstraction library for the Unix socket application programming
interface (API) featuring stream and datagram oriented communication over Unix
Domain and Internet Domain (TCP and UDP) sockets. It provides the following
key features: address abstraction (local, IPv4, and IPv6), type abstraction,
I/O timeouts, I/O stream buffering and convenience I/O functions.
It provides the following key features:
- Stand-Alone, Self-Contained, Embeddable
Although there are various Open Source libraries available which provide
a similar abstraction approach, they all either lack important features
or unfortunately depend on other companion libraries. OSSP sa fills
this gap by providing all important features (see following points) as a
stand-alone and fully self-contained library. This way OSSP sa can be
trivially embedded as a sub-library into other libraries. It especially
provides additional support for namespace-safe embedding of its API in
order to avoid symbol conflicts.
- Address Abstraction
Most of the ugliness in the Unix Socket API is the necessity to
have to deal with the various address structures (struct sockaddr_xx)
which exist because of both the different communication types and
addressing schemes. OSSP sa fully hides this by providing an abstract
and opaque address type (sa_addr_t) together with utility functions
which allow one to convert from the traditional struct sockaddr or
URI specification to the sa_addr_t and vice versa without having to
deal with special cases related to the underlying particular struct
sockaddr_xx. OSSP sa support Unix Domain and both IPv4 and IPv6
Internet Domain addressing.
- Type Abstraction
Some other subtle details in the Unix Socket API make the life hard
in practice: socklen_t and ssize_t. These two types originally
were (and on some platforms still are) plain integers or unsigned
integers while POSIX later introduced own types for them (and even
revised these types after some time again). This is nasty, because
for 100% type-correct API usage (especially important on 64-bit
machines where pointers to different integer types make trouble), every
application has to check whether the newer types exists, and if not
provide own definitions which map to the still actually used integer
type on the underlying platform. OSSP sa hides most of this in its
API and for socklen_t provides a backward-compatibility definition.
Instead of ssize_t it can use size_t because OSSP sa does not use
traditional Unix return code semantics.
- I/O Timeouts
Each I/O function in OSSP sa is aware of timeouts (set by
sa_timeout(3)), i.e., all I/O operations return SA_ERR_TMT if
the timeout expired before the I/O operation was able to succeed.
This allows one to easily program less-blocking network services.
OSSP sa internally implements these timeouts either through the
SO_{SND,RCV}TIMEO feature on more modern Socket
implementations or through traditional select(2). This way high
performance is achieved on modern platforms while the full functionality
still is available on older platforms.
- I/O Stream Buffering
If OSSP sa is used for stream communication, internally all I/O
operations can be performed through input and/or output buffers (set
by sa_buffer(3)) for achieving higher I/O performance by doing I/O
operations on larger aggregated messages and with less required system
calls. Additionally if OSSP sa is used for stream communication, for
convenience reasons line-oriented reading (sa_readln(3)) and formatted
writing (see sa_writef(3)) is provided, modelled after STDIO's fgets(3)
and fprintf(3). Both features fully leverage from the I/O buffering.
Documentation
,
.
Authors
Status
Source
Donation