docs/TCF Service - Profiler.html - tcf/org.eclipse.tcf - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <html>
 <head>
     <title>Target Communication Framework Services - Profiler</title>
 </head>

 <body lang='EN-US'>

 <h1>Target Communication Framework Services - Profiler</h1>

 <ul>
     <li><a href='#VersionHistory'>Version History</a>
     <li><a href='#Overview'>Overview</a>
     <li><a href='#Cmds'>Commands</a>
     <li><a href='#API'>API</a>
 </ul>

 <h1>Profiler Service</h1>

 <h2><a name='VersionHistory'>Version History</a></h2>

 <table border=1 cellpadding=8>
     <tr>
         <th>Version
         <th>Date
         <th>Change
     <tr>
         <td>1.0
         <td>2011-11-11
         <td>Initial
 </table>

 <h2><a name='Overview'>Overview</a></h2>

 <p><font color=#FF7000>TBD</font></p>

 <p>The service uses standard format for error reports,
 see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>

 <h2><a name='Cmds'>Commands</a></h2>

 <p><font color=#FF7000>TBD</font></p>

 <h2><a name='API'>API</a></h2>

 <pre>
 <font color=#3F5FBF>/**
  * TCF Profiler service interface.
  *
  * The service itself does not implement profiling, it manages creation/disposal of
  * profiler instances and communications between clients and profilers.
  * The service API is generic and it is supposed to support any kind of profiling and tracing.
  * A TCF agent can optionally include a profiler. The profiler would register itself with the service.
  * A client starts profiling by sending profiler configuration data for a debug context.
  * Multiple different profilers can be active at same debug context at same time.
  * If a client has started profiling, it is expected to read and process profiling data periodically.
  * Profiling data format is a contract between the profiler and its clients,
  * the service does not try to interpret the data.
  *
  * <font color=#7F9FBF>@noimplement</font> This interface is not intended to be implemented by clients.
  */</font>
 <font color=#7F0055>public interface</font> IProfiler <font color=#7F0055>extends</font> IService {

     <font color=#3F5FBF>/**
      * This service name, as it appears on the wire - a TCF name of the service.
      */</font>
     <font color=#7F0055>static final</font> String NAME = "Profiler";


     /* Profiler configuration parameters ----------------------------------- */</font>

     <font color=#3F5FBF>/**
      * Profiler configuration parameter:
      * Number: size of stack traces in profiling samples,
      * 0 means no profiling,
      * 1 means no stack tracing.
      */</font>
     <font color=#7F0055>static final</font> String PARAM_FRAME_CNT = "FrameCnt";

     <font color=#3F5FBF>/**
      * Profiler configuration parameter:
      * Number: size of profiling data buffer, in samples.
      */</font>
     <font color=#7F0055>static final</font> String PARAM_MAX_SAMPLES = "MaxSamples";


     /* Profile data properties --------------------------------------------- */</font>

     <font color=#3F5FBF>/**
      * Profile data property:
      * String: data format.
      * <font color=#7F9FBF>@since</font> 1.2
      */</font>
     <font color=#7F0055>static final</font> String PROP_FORMAT = "Format";

     <font color=#3F5FBF>/**
      * Profile data property:
      * Number: address size in bytes.
      * Default is 4 bytes.
      */</font>
     <font color=#7F0055>static final</font> String PROP_ADDR_SIZE = "AddrSize";

     <font color=#3F5FBF>/**
      * Profile data property:
      * Sample endianess.
      * Default is little-endian.
      */</font>
     <font color=#7F0055>static final</font> String PROP_BIG_ENDIAN = "BigEndian";

     <font color=#3F5FBF>/**
      * Profile data property:
      * Byte array of profile samples.
      */</font>
     <font color=#7F0055>static final</font> String PROP_DATA = "Data";


     /* Commands ------------------------------------------------------------ */</font>

     <font color=#3F5FBF>/**
      * Report profiler service capabilities to clients so they
      * can adjust to different implementations of the service.
      * <font color=#7F9FBF>@param</font> ctx - a context ID.
      * <font color=#7F9FBF>@param</font> done - command result call back object.
      * <font color=#7F9FBF>@return</font> - pending command handle.
      * <font color=#7F9FBF>@since</font> 1.3
      */</font>
     IToken getCapabilities(String ctx, DoneGetCapabilities done);

     <font color=#3F5FBF>/**
      * Call back interface for 'getCapabilities' command.
      * <font color=#7F9FBF>@since</font> 1.3
      */</font>
     <font color=#7F0055>interface</font> DoneGetCapabilities {
         <font color=#3F5FBF>/**
          * Called when 'getCapabilities' command is done.
          * <font color=#7F9FBF>@param</font> token - command handle.
          * <font color=#7F9FBF>@param</font> error - error object or null.
          * <font color=#7F9FBF>@param</font> capabilities - profiler service capabilities description.
          */</font>
         <font color=#7F0055>void</font> doneGetCapabilities(IToken token, Exception error, Map&lt;String,Object&gt; capabilities);
     }

     <font color=#3F5FBF>/**
      * Configure profiling of a debug context 'ctx'.
      * Profiling is disabled (stopped) if 'params' is empty or null.
      * <font color=#7F9FBF>@param</font> ctx - debug context to profile.
      * <font color=#7F9FBF>@param</font> params - description of profiling method, see PARAM_*.
      * <font color=#7F9FBF>@param</font> done - command result call back object.
      * <font color=#7F9FBF>@return</font> - pending command handle.
      */</font>
     IToken configure(String ctx, Map&lt;String,Object&gt; params, DoneConfigure done);

     <font color=#7F0055>interface</font> DoneConfigure {
         <font color=#3F5FBF>/**
          * Called when "configure" command is done.
          * <font color=#7F9FBF>@param</font> token - command handle.
          * <font color=#7F9FBF>@param</font> error - error object or null.
          */</font>
         <font color=#7F0055>void</font> doneConfigure(IToken token, Exception error);
     }

     <font color=#3F5FBF>/**
      * Read profiling data buffers.
      * Successful read clears the buffer.
      * If a client has started profiling with "configure" command,
      * it is expected to read and process profiling data periodically.
      * The buffer has limited size, so profiling samples can be lost if they are not read timely.
      * <font color=#7F9FBF>@param</font> ctx - debug context that is being profiled.
      * <font color=#7F9FBF>@param</font> done - command result call back object.
      * <font color=#7F9FBF>@return</font> - pending command handle.
      */</font>
     IToken read(String ctx, DoneRead done);

     <font color=#7F0055>interface</font> DoneRead {
         <font color=#3F5FBF>/**
          * Called when "read" command is done.
          * <font color=#7F9FBF>@param</font> token - command handle.
          * <font color=#7F9FBF>@param</font> error - error object or null.
          * <font color=#7F9FBF>@param</font> data - array of profile data buffers.
          * Each buffer is collection of properties, see PROP_*.
          */</font>
         <font color=#7F0055>void</font> doneRead(IToken token, Exception error, Map&lt;String,Object&gt; data[]);
     }
 }
 </pre>

 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<html>
	<head>
	<title>Target Communication Framework Services - Profiler</title>
	</head>

	<body lang='EN-US'>

	<h1>Target Communication Framework Services - Profiler</h1>

	<ul>
	<li><a href='#VersionHistory'>Version History</a>
	<li><a href='#Overview'>Overview</a>
	<li><a href='#Cmds'>Commands</a>
	<li><a href='#API'>API</a>
	</ul>

	<h1>Profiler Service</h1>

	<h2><a name='VersionHistory'>Version History</a></h2>

	<table border=1 cellpadding=8>
	<tr>
	<th>Version
	<th>Date
	<th>Change
	<tr>
	<td>1.0
	<td>2011-11-11
	<td>Initial
	</table>

	<h2><a name='Overview'>Overview</a></h2>

	<p><font color=#FF7000>TBD</font></p>

	<p>The service uses standard format for error reports,
	see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>

	<h2><a name='Cmds'>Commands</a></h2>

	<p><font color=#FF7000>TBD</font></p>

	<h2><a name='API'>API</a></h2>

	<pre>
	<font color=#3F5FBF>/**
	* TCF Profiler service interface.
	*
	* The service itself does not implement profiling, it manages creation/disposal of
	* profiler instances and communications between clients and profilers.
	* The service API is generic and it is supposed to support any kind of profiling and tracing.
	* A TCF agent can optionally include a profiler. The profiler would register itself with the service.
	* A client starts profiling by sending profiler configuration data for a debug context.
	* Multiple different profilers can be active at same debug context at same time.
	* If a client has started profiling, it is expected to read and process profiling data periodically.
	* Profiling data format is a contract between the profiler and its clients,
	* the service does not try to interpret the data.
	*
	* <font color=#7F9FBF>@noimplement</font> This interface is not intended to be implemented by clients.
	*/</font>
	<font color=#7F0055>public interface</font> IProfiler <font color=#7F0055>extends</font> IService {

	<font color=#3F5FBF>/**
	* This service name, as it appears on the wire - a TCF name of the service.
	*/</font>
	<font color=#7F0055>static final</font> String NAME = "Profiler";


	/* Profiler configuration parameters ----------------------------------- */</font>

	<font color=#3F5FBF>/**
	* Profiler configuration parameter:
	* Number: size of stack traces in profiling samples,
	* 0 means no profiling,
	* 1 means no stack tracing.
	*/</font>
	<font color=#7F0055>static final</font> String PARAM_FRAME_CNT = "FrameCnt";

	<font color=#3F5FBF>/**
	* Profiler configuration parameter:
	* Number: size of profiling data buffer, in samples.
	*/</font>
	<font color=#7F0055>static final</font> String PARAM_MAX_SAMPLES = "MaxSamples";


	/* Profile data properties --------------------------------------------- */</font>

	<font color=#3F5FBF>/**
	* Profile data property:
	* String: data format.
	* <font color=#7F9FBF>@since</font> 1.2
	*/</font>
	<font color=#7F0055>static final</font> String PROP_FORMAT = "Format";

	<font color=#3F5FBF>/**
	* Profile data property:
	* Number: address size in bytes.
	* Default is 4 bytes.
	*/</font>
	<font color=#7F0055>static final</font> String PROP_ADDR_SIZE = "AddrSize";

	<font color=#3F5FBF>/**
	* Profile data property:
	* Sample endianess.
	* Default is little-endian.
	*/</font>
	<font color=#7F0055>static final</font> String PROP_BIG_ENDIAN = "BigEndian";

	<font color=#3F5FBF>/**
	* Profile data property:
	* Byte array of profile samples.
	*/</font>
	<font color=#7F0055>static final</font> String PROP_DATA = "Data";


	/* Commands ------------------------------------------------------------ */</font>

	<font color=#3F5FBF>/**
	* Report profiler service capabilities to clients so they
	* can adjust to different implementations of the service.
	* <font color=#7F9FBF>@param</font> ctx - a context ID.
	* <font color=#7F9FBF>@param</font> done - command result call back object.
	* <font color=#7F9FBF>@return</font> - pending command handle.
	* <font color=#7F9FBF>@since</font> 1.3
	*/</font>
	IToken getCapabilities(String ctx, DoneGetCapabilities done);

	<font color=#3F5FBF>/**
	* Call back interface for 'getCapabilities' command.
	* <font color=#7F9FBF>@since</font> 1.3
	*/</font>
	<font color=#7F0055>interface</font> DoneGetCapabilities {
	<font color=#3F5FBF>/**
	* Called when 'getCapabilities' command is done.
	* <font color=#7F9FBF>@param</font> token - command handle.
	* <font color=#7F9FBF>@param</font> error - error object or null.
	* <font color=#7F9FBF>@param</font> capabilities - profiler service capabilities description.
	*/</font>
	<font color=#7F0055>void</font> doneGetCapabilities(IToken token, Exception error, Map<String,Object> capabilities);
	}

	<font color=#3F5FBF>/**
	* Configure profiling of a debug context 'ctx'.
	* Profiling is disabled (stopped) if 'params' is empty or null.
	* <font color=#7F9FBF>@param</font> ctx - debug context to profile.
	* <font color=#7F9FBF>@param</font> params - description of profiling method, see PARAM_*.
	* <font color=#7F9FBF>@param</font> done - command result call back object.
	* <font color=#7F9FBF>@return</font> - pending command handle.
	*/</font>
	IToken configure(String ctx, Map<String,Object> params, DoneConfigure done);

	<font color=#7F0055>interface</font> DoneConfigure {
	<font color=#3F5FBF>/**
	* Called when "configure" command is done.
	* <font color=#7F9FBF>@param</font> token - command handle.
	* <font color=#7F9FBF>@param</font> error - error object or null.
	*/</font>
	<font color=#7F0055>void</font> doneConfigure(IToken token, Exception error);
	}

	<font color=#3F5FBF>/**
	* Read profiling data buffers.
	* Successful read clears the buffer.
	* If a client has started profiling with "configure" command,
	* it is expected to read and process profiling data periodically.
	* The buffer has limited size, so profiling samples can be lost if they are not read timely.
	* <font color=#7F9FBF>@param</font> ctx - debug context that is being profiled.
	* <font color=#7F9FBF>@param</font> done - command result call back object.
	* <font color=#7F9FBF>@return</font> - pending command handle.
	*/</font>
	IToken read(String ctx, DoneRead done);

	<font color=#7F0055>interface</font> DoneRead {
	<font color=#3F5FBF>/**
	* Called when "read" command is done.
	* <font color=#7F9FBF>@param</font> token - command handle.
	* <font color=#7F9FBF>@param</font> error - error object or null.
	* <font color=#7F9FBF>@param</font> data - array of profile data buffers.
	* Each buffer is collection of properties, see PROP_*.
	*/</font>
	<font color=#7F0055>void</font> doneRead(IToken token, Exception error, Map<String,Object> data[]);
	}
	}
	</pre>

	</body>
	</html>