Revise several already-committed CLs.

pkg/barback/lib/src/pool.dart

 import 'dart:async';
 import 'dart:collection';
 
 import 'package:stack_trace/stack_trace.dart';
 
 /// Manages an abstract pool of resources with a limit on how many may be in use
 /// at once.
 ///
-/// When a resource is needed, the user should call [checkOut]. When the
-/// returned future completes with a [PoolResource], the resource may be
-/// allocated. Once the resource has been released, the user should call
-/// [PoolResource.release]. The pool will ensure that only a certain number of
-/// [PoolResource]s may be checked out at once.
+/// When a resource is needed, the user should call [acquire]. When the returned

[Bob Nystrom, 2013/10/29 17:25:29]

I find mixing "acquire" and "allocated" a tad confusing. Maybe instead of
"acquire", do "request"?

That way it's clear that there's a distinction between a resource you've *asked
for* (request) and a resource you've *been granted* (allocated).

[nweiz, 2013/10/29 19:27:26]

Done.

+/// future completes with a [PoolResource], the resource may be allocated. Once
+/// the resource has been released, the user should call [PoolResource.release].
+/// The pool will ensure that only a certain number of [PoolResource]s may be
+/// allocated at once.
 class Pool {
-  /// Completers for checkouts beyond the first [_maxCheckedOutResources].
+  /// Completers for acquires beyond the first [_maxAllocatedResources].
   ///
   /// When an item is released, the next element of [_pendingResources] will be
   /// completed.
   final _pendingResources = new Queue<Completer<PoolResource>>();

[Bob Nystrom, 2013/10/29 17:25:29]

Assuming the above comment, you could call this _requestedResources.

[nweiz, 2013/10/29 19:27:26]

Done.

 
-  /// The maximum number of resources that may be checked out at once.
-  final int _maxCheckedOutResources;
+  /// The maximum number of resources that may be allocated at once.
+  final int _maxAllocatedResources;
 
-  /// The number of resources that are currently checked out.
-  int _checkedOutResources = 0;
+  /// The number of resources that are currently allocated.
+  int _allocatedResources = 0;
 
   /// The timeout timer.
   ///
   /// If [_timeout] isn't null, this timer is set as soon as the resource limit
   /// is reached and is reset every time an resource is released or a new
   /// resource is requested. If it fires, that indicates that the caller became
   /// deadlocked, likely due to files waiting for additional files to be read
   /// before they could be closed.
   Timer _timer;
 
   /// The amount of time to wait before timing out the pending resources.
   Duration _timeout;
 
   /// Creates a new pool with the given limit on how many resources may be
-  /// checked out at once.
+  /// allocated at once.
   ///
   /// If [timeout] is passed, then if that much time passes without any activity
-  /// all pending [checkOut] futures will throw an exception. This is indented
+  /// all pending [acquire] futures will throw an exception. This is indented
   /// to avoid deadlocks.
-  Pool(this._maxCheckedOutResources, {Duration timeout})
+  Pool(this._maxAllocatedResources, {Duration timeout})
       : _timeout = timeout;
 
-  /// Check out a [PoolResource].
+  /// Acquire a [PoolResource].
   ///
-  /// If the maximum number of resources is already checked out, this will delay
+  /// If the maximum number of resources is already allocated, this will delay
   /// until one of them is released.
-  Future<PoolResource> checkOut() {
-    if (_checkedOutResources < _maxCheckedOutResources) {
-      _checkedOutResources++;
+  Future<PoolResource> acquire() {
+    if (_allocatedResources < _maxAllocatedResources) {
+      _allocatedResources++;
       return new Future.value(new PoolResource._(this));
     } else {
       var completer = new Completer<PoolResource>();
       _pendingResources.add(completer);
-      _heartbeat();
+      _resetTimer();
       return completer.future;
     }
   }
 
-  /// Checks out a resource for the duration of [callback], which may return a
+  /// Acquires a resource for the duration of [callback], which may return a
   /// Future.
   ///
   /// The return value of [callback] is piped to the returned Future.
   Future withResource(callback()) {
-    return checkOut().then((resource) =>
+    return acquire().then((resource) =>
         new Future.sync(callback).whenComplete(resource.release));
   }
 
-  /// If there are any pending checkouts, this will fire the oldest one.
+  /// If there are any pending acquires, this will fire the oldest one.
   void _onResourceReleased() {
     if (_pendingResources.isEmpty) {
-      _checkedOutResources--;
+      _allocatedResources--;
       if (_timer != null) {
         _timer.cancel();
         _timer = null;
       }
       return;
     }
 
-    _heartbeat();
+    _resetTimer();
     var pending = _pendingResources.removeFirst();
     pending.complete(new PoolResource._(this));
   }
 
-  /// Indicates that some external action has occurred and the timer should be
-  /// restarted.
-  void _heartbeat() {
+  /// A resource has been checked out or released.

[Bob Nystrom, 2013/10/29 17:25:29]

"checked out" -> "allocated".

[nweiz, 2013/10/29 19:27:26]

Done.

+  void _resetTimer() {
     if (_timer != null) _timer.cancel();
     if (_timeout == null) {
       _timer = null;
     } else {
       _timer = new Timer(_timeout, _onTimeout);
     }
   }
 
   /// Handles [_timer] timing out by causing all pending resource completers to
   /// emit exceptions.
   void _onTimeout() {
     for (var completer in _pendingResources) {
       completer.completeException("Pool deadlock: all resources have been "
-          "checked out for too long.", new Trace.current().vmTrace);
+          "allocated for too long.", new Trace.current().vmTrace);
     }
     _pendingResources.clear();
     _timer = null;
   }
 }
 
 /// A member of a [Pool].
 ///
 /// A [PoolResource] is a token that indicates that a resource is allocated.
 /// When the associated resource is released, the user should call [release].
 class PoolResource {
   final Pool _pool;
 
   /// Whether [this] has been released yet.
   bool _released = false;
 
   PoolResource._(this._pool);
 
   /// Tells the parent [Pool] that the resource associated with this resource is
-  /// no longer allocated, and that a new [PoolResource] may be checked out.
+  /// no longer allocated, and that a new [PoolResource] may be acquired.

[Bob Nystrom, 2013/10/29 17:25:29]

"acquired" -> "allocated".

[nweiz, 2013/10/29 19:27:26]

Done.

   void release() {
     if (_released) {
       throw new StateError("A PoolResource may only be released once.");
     }
     _released = true;
     _pool._onResourceReleased();
   }
 }