From dfe76debe30983bcd0f113c73d0c3585ffa1aef9 Mon Sep 17 00:00:00 2001 From: Stefan Sprenger Date: Mon, 21 Mar 2016 22:46:33 +0100 Subject: [PATCH] Update DSF Intro Docs to current master Updates: - references from CVS to git - Old version of SDK to more recent version - many typos Change-Id: Ibea3ec63ddf0ddf6a17ed976885ef0cf593ea3d8 Signed-off-by: Stefan Sprenger --- .../dsf/intro/dsf_programming_intro.html | 109 +++++++++--------- 1 file changed, 53 insertions(+), 56 deletions(-) diff --git a/doc/org.eclipse.cdt.doc.isv/guide/dsf/intro/dsf_programming_intro.html b/doc/org.eclipse.cdt.doc.isv/guide/dsf/intro/dsf_programming_intro.html index 047ccf94437..7410992d8be 100644 --- a/doc/org.eclipse.cdt.doc.isv/guide/dsf/intro/dsf_programming_intro.html +++ b/doc/org.eclipse.cdt.doc.isv/guide/dsf/intro/dsf_programming_intro.html @@ -7,7 +7,7 @@

Introduction to Programming with DSF

Summary

-This tutorial intorduces the reader to common techniques and patterns +This tutorial introduces the reader to common techniques and patterns used in the Debugger Services Framework (DSF), which is developed by the C/C++ Development Tools (CDT) @@ -89,7 +89,7 @@ Platform SDK


Copyright

-Copyright (c) 2008, 2010 Wind River Systems and others. All rights +Copyright (c) 2008, 2016 Wind River Systems and others. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at @@ -116,7 +116,7 @@ typical debugger integration and where DSF fits in.

@@ -134,20 +134,20 @@ Running example code and performing included exercises is very helpful in following this tutorial.  In order to run the examples in this tutorial the following is needed:
    -
  1. Download and install the Eclipse SDK 3.6 (http://download.eclipse.org/eclipse/downloads)
    2. -
  2. Install the Eclipse IDE for C/C++ 6.1 and DSF:
    +
  3. Download and install the Eclipse IDE for Eclipse Committers (https://www.eclipse.org/downloads/)
    4. +
  4. Install the latest version of the Eclipse IDE for C/C++ and DSF:
    1. Using Update Manager, install the Programming Languages -> Eclipse C/C++ Development Tools feature found in -the Helios -Discovery Site (http://download.eclipse.org/releases/helios).
      2. +the Mars +Discovery Site (http://download.eclipse.org/releases/mars).
  5. Check out the org.eclipse.cdt.examples.dsf -plugin, found in the /cvsroot/tools -CVS repository under the org.eclipse.cdt/dsf +plugin, found in the https://git.eclipse.org/c/cdt/org.eclipse.cdt.git/ +git repository under the https://git.eclipse.org/c/cdt/org.eclipse.cdt.git/tree/dsf/org.eclipse.cdt.examples.dsf directory.
  6. Build the examples plugin:
      7. @@ -261,7 +261,7 @@ the callback method.  As a contract with the caller, the asynchronous method has to invoke done() when its finished.  As there is no compiler support for ensuring that the asynchronous method completes the request monitor,  failure to do so results in common -but often subtle and difficult to track down bug +but often subtle and difficult to track down bug. @@ -344,8 +344,8 @@ purpose. A simple example of using the data request monitor:
      • Lines 26-27 create the data request monitor using a local class -declaraion.  Note the type parameter to DataRequestMonitor allows -for compiler checking of the type when calling getData() and setData() +declaration.  Note that the type parameter to DataRequestMonitor +allows type checking during compile time when calling getData() and setData() methods.
      • Lines 29-31 override the standard callback to print the result of the calculation to the console.
        @@ -360,7 +360,7 @@ CountingRequestMonitor can be used for this purpose.  It is configured such that it's done() method needs to be called a count number of times before the callback method is invoked. 
        -The following snipped from the AsyncQuicksort example shows a simple +The following snippet from the AsyncQuicksort example shows a simple example of using the CountingRequestMonitor:

        @@ -419,8 +419,8 @@ execution paths!
      @@ -440,7 +440,7 @@ synchronous method into an asynchronous one is another common task in DSF.  This exercise converts the AsyncQuicksort.partition() method into asynchronous AsyncQuicksort.asyncPartition(). 

      Look -for comments preceeded with "// TODO Exercise 2" in the +for comments preceded with "// TODO Exercise 2" in the org.eclipse.cdt.examples.dsf.requestmonitor.AsyncQuicksort module.

      @@ -449,7 +449,7 @@ module.

      Note: The use of a parent request monitor can simplify the code when implementing nested asynchronous -methods, since the parent requrest monitor is automatically completed -when the child requrest monitor is completed.  Unfortunately, +methods, since the parent request monitor is automatically completed +when the child request monitor is completed.  Unfortunately, failing to specify a parent request monitor when it is expected can sometimes lead to bugs.

      3 Concurrency

      The simple examples in previous section used asynchronous method -signatures, however no real asynchronous work was performed since all +signatures. However no real asynchronous work was performed since all execution was performed in the main thread.  This section examines a more typical example of a problem that DSF is intended to solve: a viewer and an asynchronous data generator.
      @@ -470,7 +470,7 @@ data access methods:
       49:  void getCount(DataRequestMonitor<Integer> rm);
       50:  void getValue(int index, DataRequestMonitor<String> rm); 
       50:  void getValue(int index, DataRequestMonitor<Integer> rm);
      @@ -556,7 +556,7 @@ from SyncDataViewer.getElements()  shows the use of Query:
      getCount() method is called
    1. Line 69 submits the query to an executor.  This is very important, because a Query object simply implements Runnable, it will -not perform the work in its exectute() method unless it is submitted to +not perform the work in its execute() method unless it is submitted to an executor. 
    2. Line 75 blocks while calling the @@ -709,7 +709,7 @@ of the generator's thread:
      color="#b22222">// If a request was dequeued, process it.
      147: if (request != null) {
      148: // Simulate a processing delay.
      149: Thread.sleep(PROCESSING_DELAY);
      149:
      150:
      151: if (request instanceof CountRequest) {
      152: processCountRequest((CountRequest)request);
      name="line157">157: // loop and thread will exit.
      158: request.fRequestMonitor.done();
      159: break;
      160: }
      161: }
      162:
      163: // Simulate data changes.
      164: randomChanges();
      165: }
      166: }
      167: catch (InterruptedException x) {}
      168: }
      + name="line160">160: }
      161: }else{
      162: Thread.sleep(PROCESSING_DELAY);
      163: }
      164:
      165: // Simulate data changes.
      166: randomChanges();
      167: }
      168: }
      169: catch (InterruptedException x) {}
      170: }
      @@ -831,7 +833,7 @@ access and modify any of the variables protected by this executor.  This exercise demonstrates performing a somewhat more complicated operation on protected state data.

      Look -for comments preceeded with "// TODO Exercise 3" in the +for comments preceded with "// TODO Exercise 3" in the org.eclipse.cdt.examples.dsf.dataviewer.DataGeneratorWithExcecutor module.

      @@ -844,7 +846,7 @@ what are the rules governing access to the various data objects.  In a DSF system, it is even more important to identify which data objects can only be accessed using a designated DSF executor.  Since there is no Java language mechanisms for this purpose, DSF -defines a number annotations that can be used for this purpose.  +defines a number of annotations that can be used for this purpose.  The annotations are hierarchical, so that if a class has a given annotation in its declaration, its members and fields are assumed to have the same access restriction unless otherwise specified.
      @@ -883,7 +885,7 @@ never be called using the executor belonging to the data provider.
      Note: The DSF synchronization annotations are no more than a comment intended to help make the code more understandable and maintainable.  Unfortunately, since there -is no compiler enforcment of their presence, it is easy to forget to +is no compiler enforcement of their presence, it is easy to forget to add them.
      @@ -903,7 +905,7 @@ This exercise adds the appropriate synchronization annotations to the methods and fields of DataProviderWithExecutor.

      Look -for comments preceeded with "// TODO Exercise 4" in the +for comments preceded with "// TODO Exercise 4" in the org.eclipse.cdt.examples.dsf.dataviewer.DataGeneratorWithExcecutor module.

      @@ -925,7 +927,7 @@ purposefully puts the data viewer system into a deadlock.  The deadlock first renders the data viewer unusable, but the main thread also gets deadlocked when attempting to exit the program.

      Look -for comments preceeded with "// TODO Exercise 5" in the +for comments preceded with "// TODO Exercise 5" in the org.eclipse.cdt.examples.dsf.dataviewer.SyncDataViewer module.

      @@ -996,7 +998,7 @@ alarm context.
      3. -The Timers example also features a user interface for displaying and +The Timers example also features an user interface for displaying and manipulating the data in the example's services.  The principal component of this UI is a view that can be opened by following the menus: Window->Show View->Other, @@ -1416,7 +1418,7 @@ listener methods using reflection. 

      1. Call DsfSession.dispatchEvent(Object -event, Dictionary<String, String> serviceProperties) +event, Dictionary<?, ?> serviceProperties) method.  The second parameter allows service listeners to filter events using specific service properties.
      @@ -1427,8 +1429,8 @@ listener method (method name is not important), which takes an event parameter. The type of the event parameter depends on the event, where the listener will receive all service events which can be cast to the declared type.  A -second optional parameter of type Dictionary<String, -String> allows the event listener to examine the properties +second optional parameter of type Dictionary<?, +?> allows the event listener to examine the properties of the service that is sending the event.
    3. Add itself as a service event listener by calling DsfSession.addServiceEventListener().
      4. @@ -1532,7 +1534,7 @@ use is optional.

      6.2 Context Hierarchy

      One of the most powerful features of the IDMContext interface is that -is is hierarchical.  The IDMContext.getParents() +it is hierarchical.  The IDMContext.getParents() method returns the immediate ancestors of a given context and following the parents' parents allows clients to traverse the full hierarchy of a context. 
      @@ -1706,7 +1708,7 @@ mechanism.
      Note: The limitation of posed by -the adapter problem can best be obseved with the Standard Debug Model +the adapter problem can best be observed with the Standard Debug Model implementation of the Flexible Hierarchy API.  If a developer would like to extend the Java Debugger to provide a custom Label Provider for a Java Stack Frame, than that developer would have to @@ -1718,7 +1720,7 @@ Provider for it.

      7.3 Model Proxy Problem

      -There is a second major challange in implementing the flexible +There is a second major challenge in implementing the flexible hierarchy API, which stems from the different life-cycles of the Content Provider and Model Proxy objects. 
        @@ -1750,12 +1752,12 @@ Content Provider and Model Proxy lifecycles.
        In practice this arrangement means that the content provider and the -model proxy are implemented using separate object.  However, both +Model Proxy are implemented using separate objects.  However, both objects need to have knowledge of the layout of elements in the view in order to function correctly.

        7.4 View Model Design

        The DSF View Model is a collection of objects which retrieves -information from a data model and uses that information to pupulate the +information from a data model and uses that information to populate the content of one or more Flexible Hierarchy viewers. 

        adapter is the top-level object in the view model hierarchy. All the content updates from the viewers are handled by a single instance of the VM Adapter.  The VM Adapter then delegates the handling of -these updates to the appropriate VM Providern based on the presentation +these updates to the appropriate VM Provider based on the presentation context contained in the update object.
      • VM Provider - @@ -1831,7 +1833,7 @@ Model Design Diagram and Content update handling.
        • @@ -1879,11 +1881,11 @@ Example's Data Model
        Note: The most important feature of the DSF View Model design is how it overcomes the Adapter Problem.  The VM Contexts are used to redirect getAdapter() -requrests from the viewer to the appropriate object.  In this way +requests from the viewer to the appropriate object.  In this way a particular can have many different View Model representations, rather than just one.

        Timers View Model

        -When presentated in a view in a tree hierarchy, either the timers or +When presented in a view in a tree hierarchy, either the timers or the triggers can be shown as top-level elements.  In the View Model, the layout configuration is controlled by the configuration of the VM Nodes within a given VM Provider.  This configuration can -be easily changes as it is done in the Timers example (see figure +be easily changed as it is done in the Timers example (see figure below).
        @@ -1916,7 +1918,7 @@ and number of children for each element in the path. 

        Event handling in VM Provider

        The VM Provider is the object in the View Model that listens for Data -Model events.  The events hare handled in the following steps:
        +Model events.  The events are handled in the following steps:
        1. The VM Provider receives the vent from the Data Model.
        2. The VM Provider calls the IVMNode.getDeltaFlags() for each node @@ -2140,7 +2142,7 @@ update.
          3. In some use cases, it is desirable to freeze a given view from updating and to preserve its content even if the underlying data has -changed.  This is a particular challange for Flexible Hierarchy +changed.  This is a particular challenge for Flexible Hierarchy views because they are lazy-loading and cannot be relied on to hold the data that they have retrieved. 

          Cache
          @@ -2150,7 +2152,7 @@ Model offers an implementation of a VM Provider with an internal cache.  The cache works in the following steps:
          1. The viewer or another client requests an update (current the -cache supports daving element content and element properties data).
            2. +cache supports having element content and element properties data).
          2. The cache checks whether there is already cached data for the element in the update.
          3. If update data is in cache, skip to Step 8.
            @@ -2205,7 +2207,7 @@ a particular value in the viewer has changed since the last viewer update. To support this feature, the cache is able to save the last known value of an element upon cache reset.  The label provider can retrieve this last known value and compare it to the current value -to determine if the element should be hi-lighted in the view.
            +to determine if the element should be highlighted in the view.

            Update Policy

            The update behavior in the view is controlled by the Update Policy @@ -2236,7 +2238,7 @@ implemented in the following manner:
            all the known VM Providers. 
          4. The VM Providers process the event and when the event is fully -processed, the VM Provider notifiy the VM Adapter that the event +processed, the VM Provider notify the VM Adapter that the event handling is complete.
          5. When all VM Provider complete handling the event, the VM Adapter notifies the event observer.
            @@ -2284,16 +2286,11 @@ required.  Therefore the long term goal for DSF is to contribute it to the Eclipse Platform project.  However there are several obstacles to that plan:
              -
            1. DSF uses Java 5 features including: generics, annotations, and -the concurrency package.  The Platform project is very -conservative and is resistant to switching to Java 5.  One option -may be to keep the generics and use the Java 5 compiler to produce Java -1.3 compatible byte code.
            2. DSF relies on the Flexible Hierarchy viewer, which itself is a provisional API.  The Flexible Hierarchy viewer is a general viewer feature and it should be part of the Platform's UI component rather than the Debugger.  Contributing Flexible Hierarchy to UI -would require significant refactoring before it would be accpted.
              3. +would require significant refactoring before it would be accepted.
            3. Ideally the JDT debugger should take advantage of DSF to provide a compelling use case for this technology in the SDK.