All run control commands are fully asynchronous, which means they never wait until context is in a particular state. For example, if single step command arrives when context is running, it does not wait until it stops, but returns an error. If a command @@ -66,13 +66,13 @@ to the command and intended destination was not reached. Client can know when an why a context is suspended by listening to events.
C • <token> • RunControl • getContext • <string: context ID> •
The command retrieves context properties for given context ID. -Exact meaning of context depends on the target. +Exact meaning of context depends on the target. A context can represent an execution thread, a process, an address space, etc. A context can belong to a parent context. Contexts hierarchy can be simple plain list or it can form a tree. It is up to target agent developers to choose @@ -82,7 +82,7 @@ with same IDs, however, each service accesses its own subset of context's attributes and functionality, which is relevant to that service.
Reply:
- +R • <token> • <error report> • <context data> • @@ -134,7 +134,7 @@ contextChanged event to notify changes in context data.
C • <token> • RunControl • getChildren • <string: parent context ID> •@@ -145,23 +145,23 @@ C • <token> • RunControl • getChildren • < of context IDs retrieved by previous getChildren commands, or it can be obtained from another service. Contexts hierarchy can be simple plain list or it can form a tree. It is up to target agent developers to choose layout that is most descriptive for a given target. - +
Reply:
- +
R • <token> • <error report> • <array of context IDs> •
<array of context IDs>
⇒ null
⇒ [ <context ID list> ]
-
+
<context ID list>
⇒ <string: context ID>
⇒ <context ID list> , <string: context ID>
C • <token> • RunControl • suspend • <string: context ID> •@@ -169,9 +169,9 @@ C • <token> • RunControl • suspend • <str
The command suspends execution of given context. The command should fail if CanSuspend property of the context is false. If context's IsContainer = true, the command is propagated to context's children. Only contexts with HasState = true can be suspended.
- +Result message:
- +R • <token> • <error report> •@@ -272,24 +272,24 @@ to context's children. Only contexts with HasState = true can be resumed.
RM_REVERSE_STEP_INTO_RANGE = 15 - reverse of RM_STEP_INTO_RANGE.
-
+
Result message:
- +R • <token> • <error report> •
C • <token> • RunControl • getState • <string: context ID> •
The command retrieves current state of the context. The command should fail if HasState property of the context is false.
- +Result message:
- +
R • <token> • <error report> • <boolean: suspended> •
<int: PC> • <string: last state change reason> • <state data> •
@@ -315,24 +315,24 @@ a generic client might be able to handle it better. Predefined reasons are:
Context state properties can contain any data relevant to context state.
Definition of state properties depends on a target.
-
+
Terminate
-
+
C • <token> • RunControl • terminate • <string: context ID> •
The command terminates execution of given context. The command should fail if CanTerminate
property of the context is false.
-
+
Result message:
-
+
R • <token> • <error report> •
Events
-
+
E • RunControl • contextAdded • <array of context data> •
@@ -355,7 +355,7 @@ E • RunControl • containerResumed • <array of context IDs&g
<array of context data>
⇒ null
⇒ [ <context data list> ]
-
+
<context data list>
⇒ <object: context data>
⇒ <context data list> , <object: context data>
@@ -411,7 +411,7 @@ E • RunControl • containerResumed • <array of context IDs&g
PROP_CAN_TERMINATE = "CanTerminate";
/**
- * Context resume modes.
+ * Context resume modes.
*/
static final int
RM_RESUME = 0,
@@ -430,7 +430,7 @@ E • RunControl • containerResumed • <array of context IDs&g
/**
* State change reason of a context.
* Reason can be any text, but if it is one of predefined strings,
- * a generic client might be able to handle it better.
+ * a generic client might be able to handle it better.
*/
static final String
REASON_USER_REQUEST = "Suspended",
@@ -445,8 +445,8 @@ E • RunControl • containerResumed • <array of context IDs&g
/**
* Retrieve context info for given context ID.
- *
- * @param id – context ID.
+ *
+ * @param id – context ID.
* @param done - callback interface called when operation is completed.
*/
IToken getContext(String id, DoneGetContext done);
@@ -465,14 +465,14 @@ E • RunControl • containerResumed • <array of context IDs&g
/**
* Retrieve children of given context.
- *
+ *
* @param parent_context_id – parent context ID. Can be null –
* to retrieve top level of the hierarchy, or one of context IDs retrieved
- * by previous getContext or getChildren commands.
+ * by previous getContext or getChildren commands.
* @param done - callback interface called when operation is completed.
*/
IToken getChildren(String parent_context_id, DoneGetChildren done);
-
+
/**
* Client callback interface for getContexts().
*/
@@ -484,7 +484,7 @@ E • RunControl • containerResumed • <array of context IDs&g
*/
void doneGetChildren(IToken token, RunControlError error, Context[] contexts);
}
-
+
/**
* A context corresponds to an execution thread, process, address space, etc.
* A context can belong to a parent context. Contexts hierarchy can be simple
@@ -492,17 +492,17 @@ E • RunControl • containerResumed • <array of context IDs&g
* layout that is most descriptive for a given target. Context IDs are valid across
* all services. In other words, all services access same hierarchy of contexts,
* with same IDs, however, each service accesses its own subset of context's
- * attributes and functionality, which is relevant to that service.
+ * attributes and functionality, which is relevant to that service.
*/
interface RunControlContext {
-
- /**
+
+ /**
* Retrieve context ID.
* Same as getProperties().get("ID")
*/
String getID();
-
- /**
+
+ /**
* Retrieve parent context ID.
* Same as getProperties().get("ParentID")
*/
@@ -514,21 +514,21 @@ E • RunControl • containerResumed • <array of context IDs&g
* @return Map of context properties.
*/
Map<String,Object> getProperties();
-
+
/**
* Utility method to read context property PROP_IS_CONTAINER.
* Executing resume or suspend command on a container causes all its children to resume or suspend.
* @return value of PROP_IS_CONTAINER.
*/
boolean isContainer();
-
+
/**
* Utility method to read context property PROP_HAS_STATE.
- * Only context that has a state can be resumed or suspended.
+ * Only context that has a state can be resumed or suspended.
* @return value of PROP_HAS_STATE.
*/
boolean hasState();
-
+
/**
* Utility method to read context property PROP_CAN_SUSPEND.
* Value 'true' means suspend command is supported by the context,
@@ -538,29 +538,29 @@ E • RunControl • containerResumed • <array of context IDs&g
* @return value of PROP_CAN_SUSPEND.
*/
boolean canSuspend();
-
+
/**
* Utility method to read a 'mode' bit in context property PROP_CAN_RESUME.
* Value 'true' means resume command is supported by the context,
* however the method does not check that the command can be executed successfully in
* the current state of the context. For example, the command still can fail if context is
* already resumed.
- * @param mode - resume mode, see RM_*.
- * @return value of requested bit of PROP_CAN_RESUME.
+ * @param mode - resume mode, see RM_*.
+ * @return value of requested bit of PROP_CAN_RESUME.
*/
boolean canResume(int mode);
-
+
/**
* Utility method to read a 'mode' bit in context property PROP_CAN_COUNT.
* Value 'true' means resume command with count other then 1 is supported by the context,
* however the method does not check that the command can be executed successfully in
* the current state of the context. For example, the command still can fail if context is
* already resumed.
- * @param mode - resume mode, see RM_*.
- * @return value of requested bit of PROP_CAN_COUNT.
+ * @param mode - resume mode, see RM_*.
+ * @return value of requested bit of PROP_CAN_COUNT.
*/
boolean canCount(int mode);
-
+
/**
* Utility method to read context property PROP_CAN_TERMINATE.
* Value 'true' means terminate command is supported by the context,
@@ -585,7 +585,7 @@ E • RunControl • containerResumed • <array of context IDs&g
* @return pending command handle, can be used to cancel the command.
*/
IToken suspend(DoneCommand done);
-
+
/**
* Send a command to resume a context.
* Also resumes children if context is a container.
@@ -595,7 +595,7 @@ E • RunControl • containerResumed • <array of context IDs&g
* @return pending command handle, can be used to cancel the command.
*/
IToken resume(int mode, int count, DoneCommand done);
-
+
/**
* Send a command to terminate a context.
* @param done - command result call back object.
@@ -603,10 +603,10 @@ E • RunControl • containerResumed • <array of context IDs&g
*/
IToken terminate(DoneCommand done);
}
-
+
class RunControlError extends Exception {
}
-
+
interface DoneGetState {
void doneGetState(IToken token, Exception error, boolean suspended, String pc,
String reason, Map<String,Object> params);
@@ -626,7 +626,7 @@ E • RunControl • containerResumed • <array of context IDs&g
* @param listener - run control event listener to add.
*/
void addListener(RunControlListener listener);
-
+
/**
* Remove run control event listener.
* @param listener - run control event listener to remove.
@@ -675,14 +675,14 @@ E • RunControl • containerResumed • <array of context IDs&g
/**
* Called when target simultaneously suspends multiple threads in a container
* (process, core, etc.).
- *
+ *
* @param context - ID of a context responsible for the event. It can be container ID or
* any one of container children, for example, it can be thread that hit "suspend all" breakpoint.
* Client expected to move focus (selection) to this context.
* @param pc - program counter of the context.
* @param reason - human readable description of suspend reason.
* @param params - additional target specific data about suspended context.
- * @param suspended_ids - full list of all contexts that were suspended.
+ * @param suspended_ids - full list of all contexts that were suspended.
*/
void containerSuspended(String context, String pc,
String reason, Map<String,Object> params, String[] suspended_ids);
@@ -690,8 +690,8 @@ E • RunControl • containerResumed • <array of context IDs&g
/**
* Called when target simultaneously resumes multiple threads in a container (process,
* core, etc.).
- *
- * @param context_ids - full list of all contexts that were resumed.
+ *
+ * @param context_ids - full list of all contexts that were resumed.
*/
void containerResumed(String[] context_ids);
--
cgit v1.2.3