BoostSocket/SocketRequirements

Boost Sockets Library Requirements

It must be easy to write useful, safe network programs, avoiding the common mistakes that are all too easy to make using the platform socket API. This library is intended for use by everyday programmers solving everyday network programming problems.

User programs must be portable, even though library implementations are expected to be non-portable.

Error Handling

Because network communication is subject to failures at every step of the way, almost every function call in this library will have the potential to fail.

Error return codes as an error reporting mechanism are too subject to programmer mistake or misuse. A C++ exception based failure reporting mechanism is a major requirement. It needs to be vetted against real errors to make sure it is effective yet easy to use.

Resource Management

Because network programming objects often hold significant resources, exception-safe resource management is a major requirement. C++ based "resource acquisition is initialization" approach [Str00] is expected to be the mechanism.

Scope

The library should provide an intersection of features available on virtually all platforms which support C++ and TCP/IP.

Avoid non-portable platform specific features, no matter how beguiling. This library is not intended to solve every socket or TCP/IP network programming problem; rather the aim is to do a really good job of solving the mainstream problems.

It should be possible to use non-standard features on top of the library if required (eg deciding you want to open your socket using WSASocket on windows should not stop you from using the rest of the library).

If a highly desirable feature (non-blocking forms of certain functions, for example) is impossible to provide on "virtually all platforms which support C++ and TCP/IP," it is permissible to supply it as optional functionality. As a minimum requirement, however, such optional functionality must be present on modern UNIX and Windows based implementations. There must be a compile-time way to tell if the functionality is present.

Base on Familiar Interface

Layers

• Layer 1 - Very light weight wrappers to the socket API. Targeted at platform independence for protocol implementers.
• Layer 2 - Safe acceptor/ connector classes, perhaps with plugable marshalling.
• Layer 3 - iostream interface, possibly with searchable buffering.

Don't over-generalize

This library isn't intended to be a framework for solving all future or potential network programming problems. Limit the scope to TCP/IP and sockets, and closely related problems. For example, don't try to expand it to cover every possible network protocol, networks trafficking in other than 8-bit bytes, or other esoterica.

Encapsulate the differences between IPv4 and IPv6 to protect users and ensure programs do not become quickly obsolete.

Reduce preconditions

An over-literal wrapping of the raw Berkley or Windows sockets functions into a single socket class would result in a "fat" interface with many functions being invalid for certain uses. Such preconditions are potential sources of program error and should be eliminated by supplying several more specific socket classes.

Reasonable size

In the overall scheme of C++ libraries, sockets are part of a chapter, not a whole book. Higher level protocols, such as FTP and HTTP don't have to go in the same chapter. Don't get carried away.

Boost Library Requirements and Guidelines as usual. One unusual aspect of network programming is that even the most basic safe-programming practices are often not observed by well-known books and header files. Examples include code which isn't const correct and use of dangerous all lowercase macro names ("send"). Take special care to ensure that such dangerous headers are never included in Boost interface code.

Acknowledgements

The layering requirement and example was suggested by Iain Hanson.

References

 [Don01] Donahoo, Michael J, and Calvert, Kenneth L, "The Pocket Guide to TCP/IP Sockets", 2001, ISBN  1-55860-686-6 (alternate, search)
 Light-weight, introductory-level. Probably not of interest to Boost programmers.

 [Nad00] Nadelson, Mark, and Hagan, Tom, "C++ Objects for making UNIX and WinNT? Talk", 2000, ISBN  1-929629-07-9 (alternate, search)
 Interesting mostly because it attacks portability and layering problems. The C++ code presented does not always follow 
 the best practices. Comes complete with source code. Not a good primary source.

 [Sch01]  Schmidt, Douglas C. and Huston , Stephen D. "C++ Network Programming, Vol. 1: Mastering Complexity with 
          ACE and Patterns", 2001, ISBN  0201604647 (alternate, search)
 Guide to the Adaptive Communiction Environment (ACE) which explains both interfaces and design tradeoffs used in ACE's 
 implementation of portable sockets anc concurrency mechanisms.

 [Sna00]  Snader, Jon, "Effective TCP/IP Programming", 2000, ISBN  0201615894 (alternate, search)
 Recommended reading for both users and implementors. The subtitle "44 Tips to Improve Your Network Programs" might suggest 
 disjoint presentation, but in fact this book flows well from cover-to-cover.  If you are only going to buy one TCP/IP book, 
 this could well be it.

 [Ste98]  Stevens, W. Richard, "UNIX Network Programming", Volume 1, "Networking APIs: Sockets and XTI", 2nd Edition, ISBN  0-13-490012-X (alternate, search)
 Heavy-weight, authoritative, reference. 1000 pages, probably far more interesting to implementors than users.

 [Str00]  Stroustrup, Bjarne, "The C++ Programming Language", Special Edition, 2000, ISBN  0-201-70073-5 (alternate, search)
 If you don't already own this (or perhaps the 3rd edition), you are in the wrong place.

© Copyright 2001, Beman Dawes

 Revised 30 July, 2001
 Revised 17 November, 2002 - Hugo Duncan