Improve accept logic (#21)

Handle accept errors using an exponential backoff strategy. Also uses a
semaphore to limit the max number connections.

Adds inline documentation and comments.

Author: carllerche

src/lib.rs

@@ -1,4 +1,29 @@
-pub const DEFAULT_PORT: &str = "6379";
+//! A minimal (i.e. very incomplete) implementation of a Redis server and
+//! client.
+//!
+//! The purpose of this project is to provide a larger example of an
+//! asynchronous Rust project built with Tokio. Do not attempt to run this in
+//! production... seriously.
+//!
+//! # Layout
+//!
+//! The library is structured such that it can be used with guides. There are
+//! modules that are public that probably would not be public in a "real" redis
+//! client library.
+//!
+//! The major components are:
+//!
+//! * `server`: Redis server implementation. Includes a single `run` function
+//!   that takes a `TcpListener` and starts accepting redis client connections.
+//!
+//! * `client`: an asynchronous Redis client implementation. Demonstrates how to
+//!   build clients with Tokio.
+//!
+//! * `cmd`: implementations of the supported Redis commands.
+//!
+//! * `frame`: represents a single Redis protocol frame. A frame is used as an
+//!   intermediate representation between a "command" and the byte
+//!   representation.
 
 pub mod client;
 
@@ -22,8 +47,25 @@ pub mod server;
 mod shutdown;
 use shutdown::Shutdown;
 
+/// Default port that a redis server listens on.
+///
+/// Used if no port is specified.
+pub const DEFAULT_PORT: &str = "6379";
+
 /// Error returned by most functions.
+///
+/// When writing a real application, one might want to consider a specialized
+/// errror handling crate or defining an error type as an `enum` of causes.
+/// However, for our example, using a boxed `std::error::Error` is sufficient.
+///
+/// For performance reasons, boxing is avoided in any hot path. For example, in
+/// `parse`, a custom error `enum` is defined. This is because the error is hit
+/// and handled during normal execution when a partial frame is received on a
+/// socket. `std::error::Error` is implemented for `parse::Error` which allows
+/// it to be converted to `Box<dyn std::error::Error>`.
 pub type Error = Box<dyn std::error::Error + Send + Sync>;
 
 /// A specialized `Result` type for mini-redis operations.
+///
+/// This is defined as a convenience.
 pub type Result<T> = std::result::Result<T, Error>;