Wrap long lines in README

Author: jorangreef

README.md

@@ -1,20 +1,47 @@
 # crypto-async
-Native Cipher, Hash, and HMAC operations executed in Node's threadpool for multi-core throughput.
+Native Cipher, Hash, and HMAC operations executed in Node's threadpool for
+multi-core throughput.
 
 ## Motivation
 #### Some issues with parts of the `crypto` module
-* `crypto` cipher, hash and hmac streams are not really asynchronous. They execute in C++, but only in the main thread and so they still block the event loop. Encrypting 64 MB of data might block the event loop for +/- 70ms. Hashing 64 MB of data might block the event loop for +/- 190ms.
-* These `crypto` operations do not take advantage of multiple CPU cores. Your server may have 4 cores available but `crypto` will use only 1 of these 4 cores for all encrypting and hashing operations.
-* These `crypto` operations were not designed to use statically allocated buffers. They allocate a new output buffer when encrypting or hashing data, even if you already have an output buffer available. If you want to hash only a portion of a buffer you must first create a slice. Thousands of JS object allocations put unnecessary strain on the GC. This in turn leads to longer GC pauses which also block the event loop.
-* These `crypto` operations require multiple roundtrips between JS and C++ even if you are only encrypting or hashing a single buffer.
-* These `crypto` operations are not suitable for high-throughput network protocols or filesystems which need to checksum and encrypt/decrypt large amounts of data. Such a user-space network protocol or filesystem using `crypto` might actually saturate a single CPU core with crypto operations before saturating a fast local network or SSD disk.
+* `crypto` cipher, hash and hmac streams are not really asynchronous. They
+execute in C++, but only in the main thread and so they still block the event
+loop. Encrypting 64 MB of data might block the event loop for +/- 70ms. Hashing
+64 MB of data might block the event loop for +/- 190ms.
+* These `crypto` operations do not take advantage of multiple CPU cores. Your
+server may have 4 cores available but `crypto` will use only 1 of these 4 cores
+for all encrypting and hashing operations.
+* These `crypto` operations were not designed to use statically allocated
+buffers. They allocate a new output buffer when encrypting or hashing data, even
+if you already have an output buffer available. If you want to hash only a
+portion of a buffer you must first create a slice. Thousands of JS object
+allocations put unnecessary strain on the GC. This in turn leads to longer GC
+pauses which also block the event loop.
+* These `crypto` operations require multiple roundtrips between JS and C++ even
+if you are only encrypting or hashing a single buffer.
+* These `crypto` operations are not suitable for high-throughput network
+protocols or filesystems which need to checksum and encrypt/decrypt large
+amounts of data. Such a user-space network protocol or filesystem using `crypto`
+might actually saturate a single CPU core with crypto operations before
+saturating a fast local network or SSD disk.
 
 #### Some new ideas with the `crypto-async` module
-* Truly asynchronous. All calls execute asynchronously in the `node.js` threadpool. This keeps the main thread and event loop free without blocking.
-* Scalable across multiple CPU cores. While `crypto-async` is a fraction slower per call than `crypto` (possibly because of the overhead of interacting with the threadpool), for buffers larger than 1024 bytes it shines and provides N-cores more throughput. `crypto-async` achieves up to 3x more throughput compared to `crypto`.
-* Zero-copy. All keys, ivs, source and target arguments can be passed directly using offsets into existing buffers, without requiring any slices and without allocating any temporary output buffers. This enables predictable memory usage for programs with tight memory budgets.
-* Designed to support the common use-case of encrypting or hashing a single buffer, where memory is adequate and buffers are already in memory. This avoids multiple round-trips between JS and C++.
-* Separates the control plane and the data plane to enable high-throughput applications.
+* Truly asynchronous. All calls execute asynchronously in the `node.js`
+threadpool. This keeps the main thread and event loop free without blocking.
+* Scalable across multiple CPU cores. While `crypto-async` is a fraction slower
+per call than `crypto` (possibly because of the overhead of interacting with the
+threadpool), for buffers larger than 1024 bytes it shines and provides N-cores
+more throughput. `crypto-async` achieves up to 3x more throughput compared to
+`crypto`.
+* Zero-copy. All keys, ivs, source and target arguments can be passed directly
+using offsets into existing buffers, without requiring any slices and without
+allocating any temporary output buffers. This enables predictable memory usage
+for programs with tight memory budgets.
+* Designed to support the common use-case of encrypting or hashing a single
+buffer, where memory is adequate and buffers are already in memory. This avoids
+multiple round-trips between JS and C++.
+* Separates the control plane and the data plane to enable high-throughput
+applications.
 
 ## Performance
 ```
@@ -100,15 +127,33 @@ npm install crypto-async
 ## Usage
 
 #### Adjust threadpool size and control concurrency
-Node runs filesystem and DNS operations in the threadpool. The threadpool consists of 4 threads by default. This means that at most 4 operations can be running at any point in time. If any operation is slow to complete, it will cause head-of-line blocking. The size of the threadpool should therefore be increased at startup time (at the top of your script, before requiring any modules) by setting the `UV_THREADPOOL_SIZE` environment variable (the absolute maximum is 128 threads, which requires only ~1 MB memory in total according to the [libuv docs](http://docs.libuv.org/en/v1.x/threadpool.html)).
-
-Conventional wisdom would set the number of threads to the number of CPU cores, but most operations running in the threadpool are not run hot, they are not CPU-intensive and block mostly on IO. Issuing more IO operations than there are CPU cores will increase throughput and will decrease latency per operation by decreasing queueing time. On the other hand, `crypto-async` operations are CPU-intensive. Issuing more `crypto-async` operations than there are CPU cores will not increase throughput and will increase latency per operation by increasing queueing time.
+Node runs filesystem and DNS operations in the threadpool. The threadpool
+consists of 4 threads by default. This means that at most 4 operations can be
+running at any point in time. If any operation is slow to complete, it will
+cause head-of-line blocking. The size of the threadpool should therefore be
+increased at startup time (at the top of your script, before requiring any
+modules) by setting the `UV_THREADPOOL_SIZE` environment variable (the absolute
+maximum is 128 threads, which requires only ~1 MB memory in total according to
+the [libuv docs](http://docs.libuv.org/en/v1.x/threadpool.html)).
+
+Conventional wisdom would set the number of threads to the number of CPU cores,
+but most operations running in the threadpool are not run hot, they are not
+CPU-intensive and block mostly on IO. Issuing more IO operations than there are
+CPU cores will increase throughput and will decrease latency per operation by
+decreasing queueing time. On the other hand, `crypto-async` operations are
+CPU-intensive. Issuing more `crypto-async` operations than there are CPU cores
+will not increase throughput and will increase latency per operation by
+increasing queueing time.
 
 You should therefore:
 
-1. Set the threadpool size to `IO` + `N`, where `IO` is the number of filesystem and DNS operations you expect to be running concurrently, and where `N` is the number of CPU cores available. This will reduce head-of-line blocking.
+1. Set the threadpool size to `IO` + `N`, where `IO` is the number of filesystem
+and DNS operations you expect to be running concurrently, and where `N` is the
+number of CPU cores available. This will reduce head-of-line blocking.
 
-2. Allow or design for at most `N` `crypto-async` operations to be running concurrently, where `N` is the number of CPU cores available. This will keep latency within reasonable bounds.
+2. Allow or design for at most `N` `crypto-async` operations to be running
+concurrently, where `N` is the number of CPU cores available. This will keep
+latency within reasonable bounds.
 
 ```javascript
 process.env['UV_THREADPOOL_SIZE'] = 128;
@@ -164,6 +209,11 @@ cryptoAsync.hmac(algorithm, key, source,
 );
 ```
 
+### Zero-Copy Methods
+
+The following method alternatives require more arguments but support zero-copy
+crypto operations, for reduced memory overhead and GC pressure.
+
 #### Cipher (Zero-Copy)
 ```javascript
 var cryptoAsync = require('crypto-async');
@@ -271,4 +321,5 @@ node benchmark.js
 
 ## AEAD Ciphers
 
-AEAD ciphers such as GCM are currently not supported and may be added in future as an `aead` method.
+AEAD ciphers such as GCM are currently not supported and may be added in future
+as an `aead` method.