Develop

CMakeLists.txt

@@ -0,0 +1,39 @@
+# Copyright 2019 by Cliff Green
+#
+# https://github.com/connectivecpp/chops-net-ip
+#
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+# CMake 3.8 required for cxx_std_17 target_compile_features
+
+cmake_minimum_required ( VERSION 3.8 )
+
+option ( CHOPS_NET_IP_OPT_BUILD_TESTS  "Build and perform chops-net-ip tests" ON )
+option ( CHOPS_NET_IP_OPT_BUILD_EXAMPLES  "Build and perform chops-net-ip examples" OFF )
+
+project ( chops-net-ip VERSION 1.0 LANGUAGES CXX )
+
+set ( package_name "chops-net-ip" )
+
+set ( include_source_dir "${CMAKE_SOURCE_DIR}/include" )
+
+# Interface library:
+
+add_library ( ${package_name} INTERFACE )
+
+target_include_directories ( ${package_name} INTERFACE ${include_source_dir} )
+target_compile_features ( ${package_name} INTERFACE cxx_std_17)
+
+if ( CHOPS_NET_IP_OPT_BUILD_TESTS )
+  enable_testing()
+  add_subdirectory ( test )
+endif()
+
+if ( CHOPS_NET_IP_OPT_BUILD_EXAMPLES )
+  enable_testing()
+  add_subdirectory ( example )
+endif()
+
+# end of file
+

README.md

@@ -1,20 +1,24 @@
 # Chops Net IP - Connective Handcrafted Openwork Software for Asynchronous IP Networking
 
-Chops Net IP is a C++ library that makes asynchronous networking programming fun. Or at least if not fun, it makes network programming easier and safer without significantly sacrificing performance. It is built on top of the C++ Networking Technical Standard (TS) and handles Internet Protocol (IP) communications (TCP, UDP, UDP multicast). It is written using modern C++ design idioms and the latest (2017) C++ standard.
+Chops Net IP is a C++ library that makes asynchronous networking programming fun. Or at least if not fun, it makes network programming Asio, easier and safer, without significantly sacrificing performance. It is layered on top of the Asio asynchronous networking library, which is not an easy library to use correctly. It handles Internet Protocol (IP) communications including TCP, UDP, and UDP multicast. It is written using modern C++ design idioms and the latest (2017) C++ standard.
+
+Chops Net IP is not like any other high-level, general purpose C++ socket library.
+
+# License
 
 This project is distributed under the [Boost Software License](LICENSE.txt).
 
 ## Chops Net IP Release Status
 
-Release 1.0 is under development as of August 2018, awaiting `std::expected` (proposed for C++ 20) error handling improvement, CMake config file completion, and additional testing under multiple compilers and platforms.
+Release 1.0 is under development as of March 2019, awaiting `std::expected` (proposed for C++ 20) error handling improvement, CMake config file completion, and additional testing under multiple compilers and platforms.
 
 Release notes and upcoming development plans are [available here](doc/release.md).
 
 # Overview
 
-For many developers, asynchronous network programming in C++ is not easy. It is complex, has many pitfalls, and requires designing C++ code in a way that is not natural for many developers, even those with years of experience. Chops Net IP ("C"onnective "H"andcrafted "Op"enwork "S"oftware, Networking over Internet Protocol) simplifies asynchronous network programming and provides useful (and tasty!) abstractions for many types of communication patterns.
+For many software developers, asynchronous network programming in C++ is not easy. It is complex, has many pitfalls, and requires designing C++ code in a way that is not natural, even for those with years of experience. Chops Net IP ("C"onnective "H"andcrafted "Op"enwork "S"oftware, Networking over Internet Protocol) simplifies asynchronous network programming and provides useful (and tasty!) abstractions for many types of communication patterns.
 
-Chops Net IP is layered on top of the C++ Networking Technical Standard (TS). This allows it to be portable across many compilers and platforms and when the C++ Networking TS is standardized (C++ 20? We all hope!) Chops Net IP will directly use the networking facilities of the C++ standard library.
+Chops Net IP is layered on top of Chris Kohlhoff's Asio library (see [References](doc/references.md)) allowing it to be portable across many compilers and platforms. When the C++ Networking TS is standardized (possibly C++ 23 but more likely C++ 26) Chops Net IP will directly use the networking facilities of the C++ standard library.
 
 Chops Net IP simplifies application code that processes data on multiple simultaneous TCP connections or UDP endpoints. All Chops Net IP operations (from the application viewpoint) are no-wait (i.e. there are no blocking methods) and all network processing operations are performed asynchronously.
 
@@ -63,7 +67,7 @@ A detailed overview, a C++ socket library comparison, and a FAQ is [available he
 
 # C++ Language Requirements and Alternatives
 
-C++ 17 is the primary baseline for this repository.
+C++ 17 is the primary standards baseline for this repository. There is also one future C++ facility in use (`std::expected`, for better and simpler error handling).
 
 A significant number of C++ 11 features are in the implementation and API. There are also limited C++ 14 and 17 features in use, although they tend to be relatively simple features of those standards (e.g. `std::byte`, structured bindings). For users that don't want to use the latest C++ compilers or compile with C++ 17 flags, Martin Moene provides an excellent set of header-only libraries that implement many useful C++ library features, both C++ 17 as well as future C++ standards (see [References](doc/references.md)).
 
@@ -75,8 +79,8 @@ The libraries and API's have minimal (as possible) library dependencies (there a
 
 Production external dependencies:
 
-- Version 1.11 (or later) of Chris Kohlhoff's `networking-ts-impl` (Networking TS) repository is required for some components. Note that the version number is from the Asio version and may not exactly match the Networking TS version.
-- Version 0.9 (or later) of `utility-rack`, which is a repository in the same account as Chops Net IP (`shared_buffer.hpp` and `erase_where.hpp` are required).
+- Version 1.12 (or later) of Chris Kohlhoff's `asio` repository is required. Note that it is the stand-alone library, not the Boost Asio implementation.
+- Version 0.9 (or later) of `utility-rack`, which is a repository in the same GitHub account as Chops Net IP (`shared_buffer.hpp` and `erase_where.hpp` are required).
 - Version 0.1 (or later) of Martin Moene's `expected-lite` library.
 
 Test external dependencies:
@@ -90,7 +94,7 @@ See [References](doc/references.md) for additional details on the above librarie
 
 Chops Net IP has been compiled and tests run on:
 
-- g++ 7.2, Linux (Ubuntu 17.10, Linux kernel 4.13)
+- g++ 7.2, g++ 7.3, Linux (Ubuntu 17.10 - kernel 4.13, Ubuntu 18.04 - kernel 4.15)
 - (TBD, will include at least clang on linux and vc++ on Windows)
 
 # Installation
@@ -103,9 +107,7 @@ See [References](doc/references.md) for details on dependencies and inspirations
 
 # About
 
-The primary author of Chops is Cliff Green, softwarelibre at codewrangler dot net.
-
-Co-authors include ...
+The primary author of Chops is Cliff Green, cliffg at connectivecpp dot com. The primary co-author is Thurman Gillespy, thurmang at connectivecpp dot com.
 
 Contributors include ...
 

doc/about.md

@@ -1,8 +1,8 @@
 # Author Notes and Contributor Information
 
-The primary author of Chops Net IP is Cliff Green, softwarelibre at codewrangler dot net. Cliff is a software engineer and has worked for many years writing infrastructure libraries and applications for use in networked and distributed systems, typically where high reliability or uptime is required. The domains where he has worked include wireless networks, location technology, and large scale embedded and simulation systems in the military aerospace industry. He has volunteered every year at CppCon and presented at BoostCon (before it was renamed to C++ Now).
+The primary author of Chops Net IP is Cliff Green, softwarelibre at codewrangler dot net. Cliff is a software engineer, working for many years writing infrastructure libraries and applications for use in networked and distributed systems, typically where high reliability or uptime is required. The domains where he has worked include wireless networks (cellphone, pager), location technology, and large scale embedded and simulation systems in the military aerospace industry. He has volunteered every year at CppCon and presented at BoostCon (before it was renamed to C++ Now).
 
-Cliff lives in the Seattle area and you may know him from other interests including volleyball, hiking, railroading (both the model variety and the real life big ones), music, or even parent support activities (if you are having major difficulties with your teen check out the Changes Parent Support Network, http://cpsn.org).
+Cliff lives in the Seattle area and you may know him from other interests including volleyball, hiking, railroading (both the model variety and the real life big ones), music, or even parent support activities (if you are having major difficulties with your teen, check out the Changes Parent Support Network, http://cpsn.org).
 
 (Fill in info on co-authors and contributors.)
 

doc/faq.md

@@ -1,15 +1,23 @@
 # Chops Net IP FAQ
 
+- Why should I use Chops Net IP?
+  - If you need general IP (Internet Protocol) networking in your application it will make your development job easier.
+- Why not use one of the many other networking or socket libraries?
+  - Chops Net IP scales very well, using system resources efficiently. It performs well. It is portable across many compilers and platforms. It defines application customization points that few other libraries have. The abstractions it provides are flexible and useful in many domains. It provides TCP, UDP, and UDP multicasting functionality, abstracting away many of the differences between those protocols.
+- When should I not use Chops Net IP?
+  - When you need abstractions for a specific complex and widely used domain. For example, serious web server applications should consider using Boost Beast (written by Vinnie Falco) or one of the many web frameworks that are available. If absolute raw performance is needed, writing directly to the Asio API (or similar) would be better, giving up the convenience and flexibility that Chops Net IP provides.
 - Is Chops Net IP a framework?
   - No. It is a general purpose library. There are no specific network protocols required by the library and no wire protocols added by the library. It can communicate with any TCP or UDP application. Obviously the wire protocols and communication semantics need to be appropriately implemented by the application using the Chops Net IP library.
 - Wny is a queue required for outgoing data?
-  - Applications may send data faster than it can be consumed at the remote end (or passed through the local network stack). Queueing the outgoing data allows timely processing if this situation occurs. One design possibility for the library is to push the responsibility of sending the next chunk of data back to the application, but this requires a non-trivial API interaction between the library and the application. "Fire and forget" makes for an easy application API at the cost of the outgoing queue overhead.
+  - Applications may send data faster than it can be consumed at the remote end (or passed through the local network stack). Queueing the outgoing data allows timely processing if this situation occurs. There is an API design choice for outgoing data: 1) notify the application when outgoing data can be sent 2) queue the data when needed and let the Chops Net IP library manage the outgoing data notifications. The Chops Net IP API philosophy is "fire and forget" (i.e. all calls immediately return to the application), which leads to an outgoing queue. However, applications may have different memory constraints, and the Chops Net IP library allows different containers to be used (at compile) time for the outgoing queue. For example, a fixed size ring buffer or circular queue can be used (as long as the queue requirements are met).
 - What if the outgoing data queue becomes large?
   - This is an indication that the remote end is not processing data fast enough (or that data is being produced too fast). The application can query outgoing queue stats to determine if this scenario is occurring.
 - Why not provide a configuration API for a table-driven network application?
-  - There are many different formats and types of configurations, including dynamically generated configurations. Configuration should be a separate concern from the Chops Net IP library. Configuration parsing for common formats (e.g. JSON) may be added to the `component` directory (non-dependent convenience classes and functions) in the future.
-- Is Chops Net IP a complete wrapper over the C++ Networking TS?
-  - No. There are access points that expose various Networking TS facilities, and Networking TS `endpoints` are used in the Chops Net IP API. In particular, Chops Net IP provides an interface to access the underlying Networking TS socket and the application can directly set (or query) socket options (versus wrapping and exactly duplicating the functionality).
+  - There are many different formats and types of configurations, including dynamically generated configurations. Configuration should be a separate concern from the Chops Net IP library. Configuration parsing for common formats (e.g. JSON) may be added to the `component` directory (non-dependent convenience classes and functions) in the future or provided in separate repositories.
+- Are there logging or tracing facilities in Chops Net IP?
+  - No. There is not a logging library or design that is generic enough to work in every environment. Even general purpose logging libraries have a set of tradeoffs that are not acceptable for Chops Net IP. Instead, the approach taken by Chops Net IP is to provide customization points for every meaningful step in the networking processing flow. This allows the application complete flexibility in using whatever logging facilities it wishes.
+- Is Chops Net IP a complete wrapper over the Asio API?
+  - No. There are access points that expose various Asio facilities, and Asio `endpoints` are used in the Chops Net IP API. In particular, Chops Net IP provides an interface to access the underlying Asio socket and the application can directly set (or query) socket options (versus wrapping and exactly duplicating the functionality).
 - What are some of the subtle design challenges in the implementation?
   - Passing application supplied function objects through the library layers is central to the design. Since these are passed across thread boundaries at certain points, knowing when to call `std::move` versus `std::forward<F>` is crucial (and has been the source of more than one bug).
   - The shutdown notification logic is tricky and hard to get correct, specially between the TCP connection object and the TCP acceptor and TCP connector objects.

doc/lib_comparison.md

@@ -17,7 +17,7 @@ The secondary criteria includes:
 
 ## Asio and C++ Networking TS
 
-Both Asio and the C++ Networking TS provide the foundation and underlying asynchronous model for Chops Net IP. Chops Net IP is layered on top of the C++ Networking TS and could easily be ported to use Asio. Chops Net IP provides usage and abstraction advantages as outlined in the overview documentation.
+Asio provides the foundation and underlying asynchronous model for Chops Net IP. The C++ Networking TS is still in development, awaiting standardization and modularization of core components such as executors. Chops Net IP provides usage and abstraction advantages as outlined in the overview documentation.
 
 ## ACE
 

doc/overview.md

@@ -52,7 +52,7 @@ Chops Net IP states and transitions match existing standard network protocol beh
 
 Even though an implicit state transition table exists within the Chops Net IP library (matching network protocol behavior), there are not any explicit state flags or methods to query the state through the API. Instead, state transitions are handled through application supplied function object callbacks, which notify the application that something interesting has happened and containing objects for further interaction and processing. In other words, there is not an "is_connected" method with the Chops Net IP library. Instead, an application can layer its own state on top of Chops Net IP (if desired), using the function object callbacks to manage the state.
 
-Pro tip - Chops Net IP follows the implicit state model of the Networking TS and Asio (and similar) libraries where state transitions are implemented through chaining function objects on asynchronous operations. Developers familiar with implicit or explicit state transition models will be familiar with the application model defined for Chops Net IP. Chops Net IP insulates the application from the intricacies of the Networking TS API and simplifies the state transition details.
+Pro tip - Chops Net IP follows the implicit state model of the Asio library (and similar libraries) where state transitions are implemented through chaining function objects on asynchronous operations. Developers familiar with implicit or explicit state transition models will be familiar with the application model defined for Chops Net IP. Chops Net IP insulates the application from the intricacies of the Asio library and simplifies the state transition details.
 
 ![Image of Chops Net IP objects and states](object_states_diagram.png)
 
@@ -134,7 +134,7 @@ Where to provide the customization points in the API is one of the most crucial
 
 Since data can be sent at any time and at any rate by the application, a sending queue is required. The queue can be queried to find out if congestion is occurring.
 
-Mutex locking is kept to a minimum in the library. Alternatively, some of the internal handler classes take incoming parameters and post the data through the `io context`. This allows multiple threads to be calling into one internal handler and as long as the parameter data is thread-safe (which it is), thread safety is managed by the Networking TS executor and posting queue code.
+Mutex locking is kept to a minimum in the library. Alternatively, some of the internal handler classes take incoming parameters and post the data through the `io context`. This allows multiple threads to be calling into one internal handler and as long as the parameter data is thread-safe (which it is), thread safety is managed by the Asio executor and posting queue code.
 
 In the areas where data is potentially accessed concurrently, it is typically protected by `std::atomic` wraps. For example, outgoing queue statistics and `is_started` flags are all `std::atomic`. While this guarantees runtime integrity (i.e. no crashes), it does mean that statistics might have temporary inconsistency with each other. For example, an outgoing buffer might be popped from the queue exactly between an application querying and accessing two outgoing counters. This potential inconsistency is not considered to be an issue, since the queue counters are only meant for general congestion queries, not exact statistical gathering.