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:
      @@ -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.