/*! \mainpage Very Simple Cross-Platform Library Documentation
 *
 * \section intro Introduction
 *
 * VSCPL is a simple library containing some useful classes related to
 * thread handling and I/O for POSIX and Windows systems. It is
 * intended to be extended eventually, but has been written chiefly
 * for the X-Plane Remote Access plugin and its client libraries,
 * which is reflected by the rather minimal functionality.
 *
 * To avoid namespace clashes, the classes of the library are put in
 * the \c hu::varadiistvan::scpl namespace or children of it.
 *
 * \subsection threading Threading
 *
 * The usual \ref hu::varadiistvan::scpl::Thread "thread" class and
 * some threading primitives are provided:
 * \ref hu::varadiistvan::scpl::Mutex "mutexes" and
 * \ref hu::varadiistvan::scpl::CondVar "conditional variables".
 *
 * \subsection io Input/Output
 *
 * The I/O parts are somewhat generic, but currently support
 * communication via so-called "local" sockets, which are Unix sockets
 * on POSIX and named pipes on Windows. Of course, a common interface
 * is provided, so the actual details are hidden.
 *
 * Input/output handling is based on the notion of a thread waiting
 * for one or more I/O events and then handling them. For this purpose
 * an instance of the \ref hu::varadiistvan::scpl::io::Waiter class
 * should be created and then this instance should be passed to the
 * instances of other classes. Waiting can be accomplished by calling
 * its \ref hu::varadiistvan::scpl::io::Waiter::wait "wait" function
 * and optionally passing a timeout.
 *
 * A local server socket can be created by instantiation the
 * \ref hu::varadiistvan::scpl::io::LocalServerSocket class. Besides
 * the waiter, it is given a name. It is ensured that if several users
 * of the computer run programs using the same name, each will see
 * their own socket.
 *
 * A server socket needs to accept incoming connections. For this
 * purpose and \ref hu::varadiistvan::scpl::io::LocalAcceptor
 * "acceptor" instance is used, which can be acquired by calling the
 * \ref hu::varadiistvan::scpl::io::LocalServerSocket::getAcceptor
 * "getAcceptor" function. To check, if there is an incoming
 * connection, call the acceptor's
 * \ref hu::varadiistvan::scpl::io::LocalAcceptor::accept "accept"
 * function. It returns immediately with a boolean telling whether
 * there is a connection. If so, you should call the
 * \ref hu::varadiistvan::scpl::io::LocalAcceptor::getSocket
 * "getSocket" function to get the socket representing the connection.
 * If there is no incoming connection, you can wait for one using the
 * waiter. Note, that
 * \ref hu::varadiistvan::scpl::io::LocalAcceptor::accept "accept"
 * should be called once unsuccessfully before trying to wait,
 * otherwise it is not guaranteed that waiting will finish if a new
 * connection comes in.
 *
 * \c LocalAcceptor is a subclass of
 * \ref hu::varadiistvan::scpl::io::Failable "Failable", which can be
 * used to check if some error occured. If \c accept returns \c false,
 * it should be check if the failure of accepting is due to an error,
 * or is caused simply by no client wanting to connect.
 *
 * A local client socket is created by instantiation
 * \ref hu::varadiistvan::scpl::io::LocalClientSocket. It receives the
 * same name as the server socket to which we want to
 * connect. Similarly to accepting a connection on a server socket,
 * the client socket's
 * \ref hu::varadiistvan::scpl::io::LocalClientSocket::getConnector
 * "getConnector" should be called to retrieve a
 * \ref hu::varadiistvan::scpl::io::LocalConnector "LocalConnector"
 * instance. Its
 * \ref hu::varadiistvan::scpl::io::LocalConnector::connect "connect"
 * member function should be called to initiate the connection. If it
 * returns \c true, the connection has succeeded. Otherwise one can
 * wait using the socket's waiter for the connection to succeed. If
 * waiting finishes, \c connect can be called again to check, if the
 * connection has been established. In case of a \c false return
 * value, the error condition should be checked here as well.
 *
 * Once the connection has been established, the actual communication
 * can begin. Both \c LocalSocket and \c LocalClientSocket are
 * subclasses of
 * \ref hu::varadiistvan::scpl::io::BufferedStream "BufferedStream".
 * It can be used to acquire an instance of
 * \ref hu::varadiistvan::scpl::io::ReadingBuffer "ReadingBuffer" for
 * reading, and an instance of
 * \ref hu::varadiistvan::scpl::io::WritingBuffer "WritingBuffer" for
 * writing.
 *
 * To read, call the
 * \ref hu::varadiistvan::scpl::io::ReadingBuffer::read "read"
 * function. It returns \c true, if reading has succeeded, \c false
 * otherwise which may indicate an error condition or simply the fact
 * that nothing has been received yet, in which case the program can
 * wait using the \c Waiter. If data has been read, it can be accessed
 * by the buffer's methods inherited from
 * \ref hu::varadiistvan::scpl::io::Buffer "Buffer". Before reading
 * again, the buffer's
 * \ref hu::varadiistvan::scpl::io::Buffer::reset "reset" function
 * should be called, otherwise \c read just returns \c true and
 * nothing happens.
 *
 * To write, put data into the writing buffer and call its
 * \ref hu::varadiistvan::scpl::io::WritingBuffer::write "write"
 * function. If all data in the buffer could be written, it returns
 * \c true, otherwise \c false, which, again, might indicate error,
 * but also the fact that not all data could be written. In this case,
 * the program can wait, and then retry writing again, and do this
 * until finally \c write returns \c true. If writing succeeds, the
 * buffer is reset automatically, and one can put new data into it.
 *
 * The facilities described above provide for asynchronous,
 * event-based stream handling, which is perfect for programs or
 * threads that should work with several streams, timeouts and
 * possibly other events simultaneously. This is, however, not always
 * the case. It might very well be that one thread is dedicated to
 * just deal with one stream only or at least with one stream at a
 * time. In such a case this hocus-pocus with always (re)trying
 * operations and waiting can be very cumbersome. It would be much
 * better to just call a function to read or write, which would return
 * only, if the requested operation has completed.
 *
 * This is provided by the
 * \ref hu::varadiistvan::scpl::io::BlockingStream class. Its
 * constructor receives and instance of \c BufferedStream, and it
 * provides blocking read, write and flushing operations. It also has
 * a \ref hu::varadiistvan::scpl::io::BlockingStream::interrupt "interrupt"
 * function, which can be called from another thread. If the stream is
 * blocking on an operation, that operation will then return with \c
 * false, and the interrupted condition can the be
 * \ref hu::varadiistvan::scpl::io::BlockingStream::isInterrupted
 * "checked".
 *
 * \c BlockingStream has a subclass called
 * \ref hu::varadiistvan::scpl::io::DataStream "DataStream", which can
 * be used to read and write values of the primitive data types. The
 * endianness is that of the  processor, i.e. no conversion is made to
 * a common one.
 */