Add ServerOperation and queue.

pkg/analysis_server/lib/src/operation/operation.dart

Index: pkg/analysis_server/lib/src/operation/operation.dart
diff --git a/pkg/analysis_server/lib/src/operation/operation.dart b/pkg/analysis_server/lib/src/operation/operation.dart
new file mode 100644
index 0000000000000000000000000000000000000000..fcc4d2e404394c765da1801fc314b6d2df1b6daa
--- /dev/null
+++ b/pkg/analysis_server/lib/src/operation/operation.dart
@@ -0,0 +1,99 @@
+// Copyright (c) 2014, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+library operation;
+
+import 'package:analysis_server/src/analysis_server.dart';
+import 'package:analyzer/src/generated/engine.dart' show AnalysisContext;
+
+
+/**
+ * The enumeration [ServerOperationPriority] defines the priority levels used
+ * to organize [ServerOperation]s in an optimal order. A smaller ordinal value
+ * equates to a higher priority.
+ */
+class ServerOperationPriority {
+  final int ordinal;
+  final String name;
+
+  static const int COUNT = 7;
+
+  static const ServerOperationPriority ANALYSIS_NOTIFICATION = const ServerOperationPriority._(0, "ANALYSIS_NOTIFICATION");

[Paul Berry, 2014/06/02 16:04:41]

I don't understand why analysis notifications need to be a separate task.  It
seems like what the code was previously doing (firing notifications as soon as
they were available) has exactly the same effect since it effectively makes
notifications top priority.

I suspect that if we remove ANALYSIS_NOTIFICATION by firing notifications as
soon as they are available, then we will be able to collapse
ANALYSIS_PRIORITY_CONTINUE with ANALYSIS_PRIORITY, and collapse
ANALYSIS_PRIORITY with ANALYSIS, because it will be possible for a single server
operation to perform analysis in several phases and fire notifications as they
become available.  The only thing we'd lose by making this change is that if a
priority request came in while we were doing a normal analysis of a given file,
we would have to wait until that normal analysis fully completed before we could
start the new priority analysis.  Personally, I think that's an ok tradeoff to
make for now--we can always implement something more sophisticated later if we
find that this makes analysis too unresponsive.

[Brian Wilkerson, 2014/06/02 16:21:01]

There are two advantage I can think of. First, if it takes a significant amount
of time to compute the information to be passed back in a notification (which it
might not), then by separating that out into a separate task we have reduced the
latency for handling requests that have come in (especially if there are
multiple notifications for a single file). Second, we have the potential to be
able to cancel notifications that have become outdated, which would reduce the
communication overhead. I'm not sure how much that really buys us in either
case, and it might not be worth the added complexity.

[Paul Berry, 2014/06/02 16:29:25]

I would understand that if notifications weren't the highest priority type of
task.  But since they are the highest priority type of task, that means that (a)
the only requests whose latency we reduce are those that do not require doing
any analysis, and (b) in practice we will never cancel any outdated
notifications, since as soon as a set of notifications is generated, the highest
priority task will be to send them.

[Brian Wilkerson, 2014/06/02 16:42:33]

True, which means that this might not be worthwhile.
Here's the scenario I was thinking of:

1. Server processes a request telling it that a file has changed.
2. Server analyzes the file (after several iterations), and schedules a
notification.
3. Server processes a request telling it that the same file has changed again.
4. The notification can be cancelled because the data it was depending on is
out-of-date.

It seems like a very small window of opportunity, and perhaps it would never buy
us any real advantage. Again, it might not be worth the complexity this
mechanism adds.

I'm happy to have it removed, and we can investigate solutions like this if we
see a problem.

[scheglov, 2014/06/02 17:56:59]

I will remove separate priorities for notifications for now.

[Paul Berry, 2014/06/02 18:49:32]

Shoot, I think we've had some miscommunications.  I never meant to suggest
getting rid of "ANALYSIS_PRIORITY".  I meant to suggest getting rid of
"ANALYSIS_CONTINUE".

However, reading back through the code and my comments, I realize that I'd
misunderstood this code to be prioritizing analysis on a file-by-file basis, but
now I see that it's prioritizing analysis on a context-by-context basis.  That
changes things.

Now that I'm properly thinking about this code as operating on a
context-by-context basis, I'm not convinced that we want to do priorities this
way.  Effectively what we are saying is that we are going to first analyze all
contexts in round robin fashion.  Then when that's done we will do indexing
("search") for all contexts in round robin fashion.  Then when that's done we
will do refactoring for all contexts in round robin fashion.  That seems bad
because:

- By postponing indexing of context A until all other contexts have been
analyzed, we decrease the chances that the data we need for indexing is still in
the analysis cache, which means that indexing might do a lot of redundant work.

- By postponing refactoring of context A until all other contexts have been
analyzed and indexed, we penalize users who have a lot of contexts open.  If a
user requests a refactoring on context A, we really ought to focus on analyzing
and indexing context A so that we can get the refactoring done as soon as
possible--it should take priority over analyzing all other contexts.

This is making me think that maybe the only prioritization we want to do at this
point in the code is to make sure that (a) we fully operate on the priority
context (including search and refactoring) before doing operations on any other
contexts, and (b) as much as possible, we try to finish operating on one context
before moving on to the next (except when that conflicts with (a)).  Maybe
prioritization between analysis, search, and refactoring really belongs
exclusively within the context.

+  static const ServerOperationPriority ANALYSIS_PRIORITY_CONTINUE = const ServerOperationPriority._(1, "ANALYSIS_PRIORITY_CONTINUE");
+  static const ServerOperationPriority ANALYSIS_PRIORITY = const ServerOperationPriority._(2, "ANALYSIS_PRIORITY");
+  static const ServerOperationPriority ANALYSIS_CONTINUE = const ServerOperationPriority._(3, "ANALYSIS_CONTINUE");
+  static const ServerOperationPriority ANALYSIS = const ServerOperationPriority._(4, "ANALYSIS");
+  static const ServerOperationPriority SEARCH = const ServerOperationPriority._(5, "SEARCH");
+  static const ServerOperationPriority REFACTORING = const ServerOperationPriority._(6, "REFACTORING");
+
+  @override
+  String toString() => name;
+
+  const ServerOperationPriority._(this.ordinal, this.name);
+}
+
+
+/**
+ * The class [ServerOperation] defines the behavior of objects used to perform
+ * operations on a [AnalysisServer].
+ */
+abstract class ServerOperation {
+  /**
+   * Returns the priority of this operation.
+   */
+  ServerOperationPriority get priority;
+
+  /**
+   * Performs the operation implemented by this operation.
+   */
+  void perform(AnalysisServer server);
+}
+
+
+/**
+ * The interface [MergeableOperation] is a [ServerOperation] which can be merged
+ * with (and into) another [ServerOperation].
+ */
+abstract class MergeableOperation extends ServerOperation {
+  /**
+   * Merges the given operation into this one.
+   *
+   * Returns `true` if merge was successful.
+   */
+  bool mergeWith(ServerOperation operation);
+}
+
+
+/**
+ * Instances of [PerformAnalysisOperation] perform a single analysis task.
+ */
+class PerformAnalysisOperation extends ServerOperation {
+  final AnalysisContext _context;
+  final bool _isPriority;
+  final bool _isContinue;
+
+  PerformAnalysisOperation(this._context, this._isPriority, this._isContinue);
+
+  @override
+  ServerOperationPriority get priority {
+    if (_isPriority) {
+      if (_isContinue) {
+        return ServerOperationPriority.ANALYSIS_PRIORITY_CONTINUE;
+      } else {
+        return ServerOperationPriority.ANALYSIS_PRIORITY;
+      }
+    } else {
+      if (_isContinue) {
+        return ServerOperationPriority.ANALYSIS_CONTINUE;
+      } else {
+        return ServerOperationPriority.ANALYSIS;
+      }
+    }
+  }
+
+  @override
+  void perform(AnalysisServer server) {
+    server.internalPerformAnalysis(_context);
+  }
+}