Tidy up the service protocol. Begin improving the documentation.

runtime/vm/service/service.idl

 //
 // TODO(turnidge): Finish writing an idl description of the service protocol.
 //
 
 interface Service {
+  // Returns global information about the Dart VM.
   getVM() VM
 
+  // Changes the debugging name for some isolate.
+  setName(isolateId string, name string) Response
+
+  // Returns information about an isolate.
+  getIsolate(isolateId string) Isolate
+
+  // Returns a list of vm flags and their values.
   getFlagList() FlagList
 
+  // Sets the value of a vm flag
   setFlag(name string, value string) Response
 
+  // Loads an object by id from an isolate.
   getObject(isolateId string, objectId string) Object
 
   // The response is a subtype of Object or ObjectRef.
   getObjectByAddress(address string, ref bool) Response
 
   // Adds a breakpoint at the specified line.
   //
   // TODO(turnidge): Make line an int instead of a string.
   addBreakpoint(isolateId string,
                 scriptId string,
@@ skipping 19 matching lines @@
   eval(isolateId string, targetId string, expression string) InstanceRef
 
   // Returns the current execution stack for an isolate.
   getStack(isolateId string) Stack
 
   // Returns code coverage information for a library, script, class,
   // or function.
   getCoverage(isolateId string, targetId string) CodeCoverage
 
   // Returns call site cache information for a function.
-  getCallSiteData(isolateId string, targetId string) _CallSiteData
+  _getCallSiteData(isolateId string, targetId string) _CallSiteData
 
   // Returns a full cpu profile for an isolate.
   //
   // <code>tagSelector</code> is optional with default 'UserVM'.
   getCpuProfile(isolateId string, tags TagSelector) CpuProfile
 
 
   // Returns a simple tag-based profile for an isolate.
   getTagProfile(isolateId string) TagProfile
 
@@ skipping 28 matching lines @@
                        limit int) InboundReferences
 
   getClassList(isolateId string) ClassList
 
   // When <code>onlyWithInstantiations</code> is true, the list only includes
   // type arguments with instantiations. Otherwise, all type arguments are
   // returned.
   getTypeArgumentsList(isolateId string,
                        onlyWithInstantiations bool) TypeArgumentsList
 
+  // Gets a list of isolate metrics.
   getIsolateMetricList(isolateId string,
                        type MetricSelector) MetricList
 
+  // Gets a specific isolate metric by id.
   getIsolateMetric(isolateId string,
                    metricId string) Metric
 
+  // Gets a list of vm metrics.
   getVMMetricList() MetricList
 
+  // Gets a specific vm metric by id.
   getVMMetric(metricId string) Metric
 
+  // A test rpc for vm requests.
+  _echoVM(text string) _EchoResponse
+
+  // A test rpc for isolate requests.
   _echo(isolateId string,
         text string) _EchoResponse
 
-  _echoVM(text string) _EchoResponse
-
   // Triggers a ServiceEvent with EventType '_Echo'.
   _triggerEchoEvent(isolateId string,
                     text string) _EchoResponse
 
   // Response is bad JSON.
   _respondWithMalformedJson(isolateId string) Response
 
   // Response is not an object.
   _respondWithMalformedObject(isolateId string) Response
 }
@@ skipping 10 matching lines @@
   type    string
 
   // Some responses will have the <code>_vmType</code> property.  This
   // provides the VM-internal type name of an object, and is provided
   // only when this type name differs from the <code>type</code>
   // property.
   _vmType string [optional]
 }
 
 
+// An asynchronous notification from the VM Service.
+struct ServiceEvent extends Response {
+  // What kind of event is this?
+  eventType ServiceEventType
+
+  // The isolate with which this event is associated.
+  isolate IsolateRef
+
+  // The breakpoint associated with this event, if applicable.
+  //
+  // This is provided for the events:
+  //   <code>PauseBreakpoint</code>
+  //   <code>BreakpointAdded</code>
+  //   <code>BreakpointRemoved</code>
+  //   <code>BreakpointResolved</code>
+  breakpoint Breakpoint [optional]
+
+  // The top stack frame associated with this event, if applicable.
+  //
+  // This is provided for the events:
+  //   <code>PauseBreakpoint</code>
+  //   <code>PauseInterrupted</code>
+  //   <code>PauseException</code>
+  //
+  // For the <code>Resume</code> event, the top frame is provided at
+  // all times except for the initial resume event that is delivered
+  // when an isolate begins execution.
+  topFrame Frame [optional]
+
+  // The exception associated with this event, if this is a
+  // <code>PauseException</code> event.
+  exception InstanceRef [optional]
+}
+
+
+// The type of a service event.
+enum ServiceEventType {
+  // Notification that a new isolate has started.
+  IsolateStart
+
+  // Notification that an isolate has exited.
+  IsolateExit
+
+  // Notification that isolate identifying information has changed.
+  // Currently used to notify of changes to the isolate debugging name
+  // via <code>setName</code>.
+  IsolateUpdate
+
+  // An isolate has paused at start, before executing code.
+  PauseStart
+
+  // An isolate has paused at exit, before terminating.
+  PauseExit
+
+  // An isolate has paused at a breakpoint or due to stepping.
+  PauseBreakpoint
+
+  // An isolate has paused due to interruption via <code>pause</code>.
+  PauseInterrupted
+
+  // An isolate has paused due to an exception.
+  //
+  // TODO(turnidge): Allow user to toggle pause-on-exceptions.
+  PauseException
+
+  // An isolate has started or resumed execution.
+  Resume
+
+  // A breakpoint has been added for an isolate.
+  BreakpointAdded
+
+  // An unresolved breakpoint has been resolved for an isolate.
+  BreakpointResolved
+
+  // A breakpoint has been removed.
+  BreakpointRemoved
+
+  // A garbage collection event.
+  GC
+
+  // The object graph is being delivered.  This is triggered via
+  // <code>requestHeapSnapshot</code>.
+  _Graph
+}
+
+
 struct VM extends Response {
-  placeholder int
-}
-
-
+  // Word length on target architecture (e.g. 32, 64).
+  architectureBits int
+
+  // The CPU we are generating code for.
+  targetCPU string
+
+  // The CPU we are actually running on.
+  hostCPU string
+
+  // The Dart VM version string.
+  version string
+
+  // The process id for the VM.
+  pid string
+
+  // The time that the VM started in milliseconds since the epoch.
+  //
+  // Suitable to pass to DateTime.fromMillisecondsSinceEpoch.
+  startTime int
+
+  // A list of isolates running in the VM.
+  isolates []IsolateRef
+
+  // Are assertions enabled in the VM?
+  //
+  // TODO(turnidge): Move to some sort of general settings list?
+  _assertsEnabled bool
+
+  // Are type checks enabled in the VM?
+  //
+  // TODO(turnidge): Move to some sort of general settings list?
+  _typeChecksEnabled bool
+}
+
+
+// A reference to an an isolate.
+struct IsolateRef extends Object {
+  // A numeric id for this isolate, represented as a string.  Unique.
+  number string
+
+  // A name identifying this isolate.  Not guaranteed to be unique.
+  name string
+}
+
+
+// An isolate running in the VM.
+struct Isolate {
+  // A numeric id for this isolate, represented as a string.  Unique.
+  number string
+
+  // A name identifying this isolate.  Not guaranteed to be unique.
+  name string
+
+  // The time that the VM started in milliseconds since the epoch.
+  //
+  // Suitable to pass to DateTime.fromMillisecondsSinceEpoch.
+  startTime int
+
+  // The entry function for this isolate.
+  entry FunctionRef [optional]
+
+  // The number of live ports for this isolate.
+  livePorts int
+
+  // Will this isolate pause when exiting?
+  pauseOnExit bool
+
+  // The last pause event delivered to the isolate.  If the isolate is
+  // running, this will be a resume event.
+  pauseEvent ServiceEvent
+
+  // The error that is causing this isolate to exit, if applicable.
+  error Error [optional]
+
+  // The root library for this isolate.
+  rootLib LibraryRef
+
+  // A list of all libraries for this isolate.
+  libraries []LibraryRef
+
+  // A list of all breakpoints for this isolate.
+  breakpoints []Breakpoint
+
+  // A list of features enabled for this isolate.
+  features []string
+
+  // TODO
+  heaps int
+
+  // TODO
+  tagCounters int
+}
+
+
+// A list of flags.
 struct FlagList extends Response {
-  placeholder int
-}
-
-
-struct _EchoResponse extends Response {
-  text string
-}
-
-
-// Persistent objects in the vm are returned as subclasses of Object.
+  // A list of all flags which are set to default values.
+  unmodifiedFlags []Flag
+
+  // A list of all flags which have been modified by the user.
+  modifiedFlags []Flag
+}
+
+
+// A single flag.
+struct Flag {
+  // The name of the flag.
+  name string
+
+  // A description of the flag.
+  comment string
+
+  // The type of the flag.
+  flagType FlagType
+}
+
+
+// The type of a flag.
+enum FlagType {
+  bool
+  int
+  uint64_t
+  string
+}
+
+
+// A reference to a persistent object that lives in some isolate.
+struct ObjectRef extends Response {
+  // A unique identifier for an object.  Passed to
+  // <code>getObject</code> to load the full object.
+  id string
+}
+
+
+// A persistent object that lives in some isolate.
 struct Object extends Response {
-  // The object <code>id</code> can be used to refer to a persistent
-  // object inside the vm or an isolate.
-  id  string
+  // A unique identifier for this object.
+  id string
+}
+
+
+// TODO(turnidge): null type
+// TODO(turnidge): VMObject.
+
+
+// A reference to a Dart language class.
+struct ClassRef extends ObjectRef {
+  // The name of this class.
+  name string
+
+  // A vm internal name, provided only when it is different than name.
+  _vmName string
+}
+
+
+// A Dart language class.
+struct Class extends Object {
+  // The name of this class.
+  name string
+
+  // A vm internal name, provided only when it is different than name.
+  _vmName string
+
+  // The error which occurred during class finalization, if it exists.
+  error InstanceRef [optional]
+
+  // Is this an abstract class?
+  abstract bool
+
+  // Is this a const class?
+  const bool
+
+  // Has this class been finalized?
+  finalized bool
+
+  // Is this class implemented?
+  implemented bool
+
+  // Is this a vm patch class?
+  patch bool
+
+  // The library which contains this class.
+  library LibraryRef
+
+  // The script which defines this class.  May be missing for some
+  // classes.
+  script ScriptRef
+
+  // The superclass of this class, if any.
+  super ClassRef [optional]
+
+  // A list of interface types for this class.
+  interfaces []TypeRef
+
+  // A list of fields in this class.  Does not include fields from
+  // superclasses.
+  fields []FieldRef
+
+  // A list of functions in this class.  Does not include functions
+  // from superclasses.
+  functions []FunctionRef
+
+  // A list of subclasses of this class.
+  subclasses []ClassRef
+
+  // Allocation statistics for this class, if available.
+  allocationStats ClassHeapStats [optional]
+}
+
+
+struct ClassHeapStats extends Response {
+  TODO int
+}
+
+
+// A reference to a type arguments vector.
+struct TypeArgumentsRef extends ObjectRef {
+  // A name for this type argument list.
+  name string
+
+  // A vm internal name, provided only when it is different than name.
+  _vmName string
+}
+
+
+// The type argument vector for some instantiated generic type.
+struct TypeArguments extends Object {
+  // A name for this type argument list.
+  name string
+
+  // A vm internal name, provided only when it is different than name.
+  _vmName string
+
+  // A list of types.
+  types []TypeRef
+}
+
+
+// Represents an error object inside the VM.
+struct Error extends Object {
+  // An error message
+  message string
+}
+
+
+// A <code>InstanceRef</code> encodes a reference to a
+// <code>Instance</code> object.
+struct InstanceRef extends ObjectRef {
+  TODO int
+}
+
+
+struct TypeRef extends InstanceRef {
+  TODO2 int
 }
 
 
 // An <code>Instance</code> represents a Dart-language object.
 struct Instance extends Object {
-  placeholder int
+  TODO int
 }
 
 
 // A <code>Breakpoint</code> describes a debugger breakpoint.
 struct Breakpoint extends Object {
   breakpointNumber int
   resolved         bool
   location         Location
 }
 
 
-// References to persistent objects in the vm are returned as
-// subclasses of ObjectRef.
-struct ObjectRef extends Response {
-  // The object <code>id</code> can be used to refer to a persistent
-  // object inside the vm or an isolate.
-  id  string
-}
-
-
 // A <code>CodeRef</code> encodes a reference to a <code>Code</code> object.
 struct CodeRef extends ObjectRef {
-  placeholder int
-}
-
-
-struct ClassRef extends ObjectRef {
-  placeholder int
-}
-
-
-struct TypeArgumentsRef extends ObjectRef {
-  placeholder int
+  TODO int
+}
+
+
+struct LibraryRef extends ObjectRef {
+  TODO int
 }
 
 
 // A <code>FunctionRef</code> encodes a reference to a <code>Function</code> object.
 struct FunctionRef extends ObjectRef {
-  placeholder int
+  TODO int
 }
 
 
 // A <code>FieldRef</code> encodes a reference to a <code>Field</code> object.
 struct FieldRef extends ObjectRef {
-  placeholder int
-}
-
-
-// A <code>InstanceRef</code> encodes a reference to a <code>Instance</code> object.
-struct InstanceRef extends ObjectRef {
-  placeholder int
+  TODO int
 }
 
 
 // A <code>ScriptRef</code> encodes a reference to a <code>Script</code> object.
 struct ScriptRef extends ObjectRef {
-  placeholder int
-}
-
-
-struct Class extends Object {
-  placeholder int
-}
-
-
-struct TypeArguments extends Object {
-  placeholder int
-}
-
-
+  TODO int
+}
+
+
 // A <code>Location</code> encodes a location withing a dart script.
 //
 // TODO(turnidge): Should this really be broken out as its own type?
 // If so, we should use it more consistently in the api.  For example,
 // in Frame.
 struct Location {
   script   ScriptRef
   tokenPos int
 }
 
@@ skipping 15 matching lines @@
 }
 
 
 // A <code>Stack</code> represents an isolate's execution stack.
 struct Stack extends Response {
   frames []Frame
 }
 
 
 struct CodeCoverage extends Response {
-  placeholder int
+  TODO int
 }
 
 
 struct _CacheEntry {
   receiverClass ClassRef
   count         int
 }
 
 
 struct _CallSite {
@@ skipping 98 matching lines @@
 }
 
 
 struct Metric extends Response {
   name string
   description string
 }
 
 
 struct Gauge extends Metric {
-  value double
-  min double
-  max double
+  value float
+  min float
+  max float
 }
 
 
 struct Counter extends Metric {
-  value double
+  value float
 }
 
 
 // A <code>GCOption</code> is used to indicate which form of garbage
 // collection is requested.
 enum GCOption {
   full
 }
 
 // A <code>StepOption</code> is used to indicate which form of
@@ skipping 10 matching lines @@
   UserVM
   UserOnly
   VMUser
   VMOnly
   None
 }
 
 // A <code>MetricSelector</code> is used to indicate which list of metrics
 // should be retrieved from an isolate.
 enum MetricSelector {
-  Dart,
-  Native,
+  Dart
+  Native
 }
+
+
+struct _EchoResponse extends Response {
+  text string
+}