[Home]BoostSocket/SocketRequirements

BOOST WIKI | BoostSocket | RecentChanges | Preferences | Page List | Links List

Difference (from prior major revision) (no other diffs)

Changed: 1,87c1,129

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



Build on the widespread and mature network programming infrastructure
already in place. Reuse successful sockets and C++ idioms, rather than inventing new ones. The sockets interface is well known to many programmers, and numerous books,
tutorials, and other materials are available. Build on this base,
except in cases where it clearly runs counter to good C++ software
engineering practice.

Layers



Layer the design to meet the separate requirements of different types
of users. For example:

* 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

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

Build on the widespread and mature network programming infrastructure already in place. Reuse successful sockets and C++ idioms, rather than inventing new ones. The sockets interface is well known to many programmers, and numerous books, tutorials, and other materials are available. Build on this base, except in cases where it clearly runs counter to good C++ software engineering practice.

Layers

Layer the design to meet the separate requirements of different types of users. For example:

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

BOOST WIKI | BoostSocket | RecentChanges | Preferences | Page List | Links List
Edit text of this page | View other revisions
Last edited December 18, 2004 12:24 pm (diff)
Search:
Disclaimer: This site not officially maintained by Boost Developers