Move pub/barback's Pool class into its own package.

pkg/pool/README.md

Index: pkg/pool/README.md
diff --git a/pkg/pool/README.md b/pkg/pool/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..898728867ecdf306cf82e2ad985458c880ca614f
--- /dev/null
+++ b/pkg/pool/README.md
@@ -0,0 +1,53 @@
+The pool package exposes a `Pool` class which makes it easy to manage a limited
+pool of resources.
+
+The easiest way to use a pool is by calling `withResource`. This runs a callback
+and returns its result, but only once there aren't too many other callbacks
+currently running.
+
+```dart
+// Create a Pool that will only allocate 10 resources at once. After 30 seconds
+// of inactivity with all resources checked out, the pool will throw an error.
+final pool = new Pool(10, timeout: new Duration(seconds: 30));
+
+Future<String> readFile(String path) {
+  // Since the call to [File.readAsString] is within [withResource], no more

[Bob Nystrom, 2014/07/17 22:09:14]

This example would be clearer if you did something like a loop over a thousand
files.

[nweiz, 2014/07/17 22:56:55]

I'm not sure how I'd do that without adding a lot of extra text here. I'd want
the example to do something with the extra files, but something like copying
them to another location means I'd have to have a writeFile function that's also
constrained by the pool and at that point the example starts getting very large.
I really like keeping inline examples concise.

+  // than ten files will be open at once.
+  return pool.withResource(() => return new File(path).readAsString());
+}
+```
+
+For more fine-grained control, the user can also explicitly request generic
+`PoolResource` objects that can later be released back into the pool. This is
+what `withResource` does under the covers: requests a resource, then releases it
+once the callback completes.
+
+`Pool` ensures that only a limited number of resources are allocated at once.
+It's the caller's responsibility to ensure that the corresponding physical
+resource is only consumed when a `PoolResource` is allocated.
+
+```dart
+class PooledFile implements RandomAccessFile {
+  final RandomAccessFile _file;
+  final PoolResource _resource;
+
+  static Future<PooledFile> open(String path) {
+    return pool.request().then((resource) {
+      return new File(path).open().then((file) {
+        return new PooledFile._(file, resource);
+      });
+    });
+  }
+
+  PooledFile(this._file, this._resource);
+
+  // ...
+
+  Future<RandomAccessFile> close() {
+    return _file.close.then((_) {
+      _resource.release();
+      return this;
+    });
+  }
+}
+```