From 506af19b86af2a7960a3bb5cf72287349012c869 Mon Sep 17 00:00:00 2001 From: Alan Coopersmith Date: Sat, 23 Oct 2010 00:43:28 -0700 Subject: xsmp.xml: Use and related markup for protocol message definition Signed-off-by: Alan Coopersmith --- doc/xsmp.xml | 241 ++++++++++++++++++++++++++++++++++++----------------------- 1 file changed, 146 insertions(+), 95 deletions(-) diff --git a/doc/xsmp.xml b/doc/xsmp.xml index 1677cda..ee4bc14 100644 --- a/doc/xsmp.xml +++ b/doc/xsmp.xml @@ -411,44 +411,53 @@ set of valid responses and possible error messages are listed. The ICE severity is given in parentheses following each error class. - RegisterClient [Client → SM] + +RegisterClient [Client → SM] - previous-ID: ARRAY8 + previous-ID: ARRAY8 - Valid Responses: RegisterClientReply + Valid Responses: RegisterClientReply - Possible Errors: BadValue (CanContinue) + Possible Errors: BadValue (CanContinue) + The client must send this message to the SM to register the client's existence. If a client is being restarted from a previous session, -the previous-ID field must contain the client ID from the previous -session. For new clients, previous-ID should be of zero length. +the previous-ID field must contain the client +ID from the previous session. For new clients, +previous-ID should be of zero length. -If previous-ID is not valid, the SM will send a BadValue +If previous-ID is not valid, +the SM will send a BadValue error message to the client. At this point the SM reverts to the register state and waits for another RegisterClient The client should then send a RegisterClient with a -null previous-ID field. +null previous-ID field. - RegisterClientReply [Client ← SM] + +RegisterClientReply [Client ← SM] - client-ID: ARRAY8 + client-ID: ARRAY8 + -The client-ID specifies a unique identification for this client. If -the client had specified an ID in the previous-ID field of -the RegisterClient message, client-ID will be -identical to the previously specified ID. If previous-ID was null, -client-ID will be a unique ID freshly generated by the SM. The -client-ID format is specified in section 6. +The client-ID specifies a unique identification +for this client. If the client had specified an ID in the +previous-ID field of the +RegisterClient message, +client-ID will be identical to the previously +specified ID. If previous-ID was null, +client-ID will be a unique ID freshly generated +by the SM. The client-ID format is specified in +section 6. -If the client didn't supply a previous-ID field to +If the client didn't supply a previous-ID field to the Register­Client message, the SM must send a SaveYourself message with type = Local, shutdown = False, interact-style = None, and fast = False immediately @@ -457,27 +466,30 @@ respond to this like any other Save­Yourself message. - SaveYourself [Client ← SM] + +SaveYourself [Client ← SM] - type: SAVE_TYPE - shutdown: BOOL - interact-style: INTERACT_STYLE - fast: BOOL + type: SAVE_TYPE + shutdown: BOOL + interact-style: INTERACT_STYLE + fast: BOOL - Valid Responses: + Valid Responses: SetProperties DeleteProperties GetProperties SaveYourselfDone SaveYourselfPhase2Request - InteractRequest + InteractRequest + The SM sends this message to a client to ask it to save its state. The client writes a state file, if necessary, and, if necessary, uses SetProperties to inform the SM of how to restart it and how to discard the saved state. During this process it -can, if allowed by interact-style, request permission to interact with +can, if allowed by interact-style, request permission +to interact with the user by sending an InteractRequest message. After the state has been saved, or if it cannot be successfully saved, and the properties are appropriately set, the client sends @@ -492,10 +504,11 @@ a ShutdownCancelled message. -If interact-style is None the client must not -interact with the user while saving state. If the interact-style +If interact-style is None the +client must not interact with the user while saving state. If the +interact-style is Errors the client may interact with the user -only if an error condition arises. If interact-style +only if an error condition arises. If interact-style is Any then the client may interact with the user for any purpose. This is done by sending an Interact­Request message. The SM will @@ -526,8 +539,8 @@ responding as appropriate to the newly received -The type field specifies the type of information that should be -saved: Global Local +The type field specifies the type of information that +should be saved: Global Local or Both The Local type indicates that the application must update the properties to reflect its current state, send @@ -573,13 +586,16 @@ to remove it. -Once the SM has send SaveYourself to a client, it can't send another SaveYourself to that client until the client either responds with a SaveYourselfDone or the SM sends a ShutdownCancelled +Once the SM has send SaveYourself to a client, it +can't send another SaveYourself to that client until +the client either responds with a SaveYourselfDone or +the SM sends a ShutdownCancelled Advice to Implementors -If the client stores local any state in a file or similar "Qexternal" +If the client stores local any state in a file or similar "external" storage, it must create a distinct copy in response to each SaveYourself message. It must not simply refer to a previous @@ -590,7 +606,8 @@ needed for the new checkpoint. -The shutdown field specifies whether the system is being shut down. +The shutdown field specifies whether the system is +being shut down. Rationale @@ -607,19 +624,22 @@ user does after the save will be lost. -The fast field specifies whether or not the client should save its -state as quickly as possible. For example, if the SM knows that power -is about to fail, it should set the fast field to True +The fast field specifies whether or not the client +should save its state as quickly as possible. For example, if the SM knows +that power is about to fail, it should set the fast +field to True. - SaveYourselfPhase2 [Client → SM] + +SaveYourselfPhase2 [Client → SM] - Valid Responses: + Valid Responses: SetProperties DeleteProperties GetProperties SaveYourselfDone - InteractRequest + InteractRequest + The SM sends this message to a client that has previously sent @@ -648,15 +668,17 @@ and the properties are appropriately set, the client sends a SaveYourselfDone message. - SaveYourselfRequest [Client → SM] + +SaveYourselfRequest [Client → SM] - type: SAVE_TYPE - shutdown: BOOL - interact-style: INTERACT_STYLE - fast: BOOL - global: BOOL + type: SAVE_TYPE + shutdown: BOOL + interact-style: INTERACT_STYLE + fast: BOOL + global: BOOL - Valid Responses: SaveYourself + Valid Responses: SaveYourself + An application sends this to the SM to request a checkpoint. When the @@ -672,20 +694,23 @@ is about to be lost. -If global is set to True then the +If global is set to True then the resulting SaveYourself should be sent to all -applications. If global is set to False then the +applications. If global is set to +False then the resulting SaveYourself should be sent to the application that sent the Save­Yourself­Request - InteractRequest [Client → SM] + +InteractRequest [Client → SM] - dialog-type: DIALOG_TYPE + dialog-type: DIALOG_TYPE - Valid Responses: Interact ShutdownCancelled + Valid Responses: Interact ShutdownCancelled - Possible Errors: BadState (CanContinue) + Possible Errors: BadState (CanContinue) + During a checkpoint or session-save operation, only one client at a @@ -696,15 +721,17 @@ shutdown is not cancelled by another client first. -The dialog-type field specifies either Errors -indicating that the client wants to start an error dialog -or Normal meaning the client wishes to start a -non-error dialog. +The dialog-type field specifies either +Errors indicating that the client wants to start an +error dialog or Normal meaning the client wishes +to start a non-error dialog. - Interact [Client ← SM] + +Interact [Client ← SM] - Valid Responses: InteractDone + Valid Responses: InteractDone + This message grants the client the privilege of interacting with the @@ -719,36 +746,40 @@ sending a InteractDone the client should abort the interaction and send a SaveYourselfDone - InteractDone [Client → SM] + +InteractDone [Client → SM] - cancel-shutdown: BOOL + cancel-shutdown: BOOL - Valid Responses: ShutdownCancelled + Valid Responses: ShutdownCancelled + This message is used by a client to notify the SM that it is done interacting. -Setting the cancel-shutdown field to True +Setting the cancel-shutdown field to True indicates that the user has requested that the entire shutdown be -cancelled. Cancel-shutdown may only be True if +cancelled. Cancel-shutdown may only be True if the corresponding SaveYourself message specified True for the shutdown field and Any or Errors for the -interact-style field. Otherwise, cancel-shutdown must -be False +interact-style field. Otherwise, +cancel-shutdown must be False. - SaveYourselfDone [Client → SM] + +SaveYourselfDone [Client → SM] - success: BOOL + success: BOOL - Valid Responses: + Valid Responses: SaveComplete Die ShutdownCancelled - + + This message is sent by a client to indicate that all of the @@ -757,33 +788,38 @@ sending SaveYourselfDone the client must wait for a SaveComplete ShutdownCancelled or Die message before changing its state. If the SaveYourself operation was successful, then -the client should set the success field to True -otherwise the client should set it to False +the client should set the success field to +True otherwise the client should set it to +False. Example If a client tries to save its state and runs out of disk space, it -should return False in the success field of -the SaveYourselfDone message. +should return False in the success +field of the SaveYourselfDone message. - SaveYourselfPhase2Request [Client → SM] + +SaveYourselfPhase2Request [Client → SM] - Valid Responses: + Valid Responses: ShutdownCancelled SaveYourselfPhase2 - + + This message is sent by a client to indicate that it needs to be informed when all the other clients are quiescent, so it can continue its state. - Die [Client ← SM] + +Die [Client ← SM] - Valid Responses: ConnectionClosed + Valid Responses: ConnectionClosed + When the SM wants a client to die it sends a Die @@ -792,9 +828,11 @@ a ConnectionClosed message and may then close its connection to the SM at any time. - SaveComplete [Client → SM] + +SaveComplete [Client → SM] - Valid Responses: + Valid Responses: + When the SM is done with a checkpoint, it will send each of the @@ -802,7 +840,9 @@ clients a SaveComplete message. The client is then free to change its state. - ShutdownCancelled [Client ← SM] + +ShutdownCancelled [Client ← SM] + The shutdown currently in process has been aborted. The client can @@ -814,9 +854,11 @@ continue with the save and send a SaveYourselfDone with the success field set to reflect the outcome of the save. - ConnectionClosed [Client → SM] + +ConnectionClosed [Client → SM] - reason: LISTofARRAY8 + reason: LISTofARRAY8 + Specifies that the client has decided to terminate. It should be @@ -824,8 +866,8 @@ immediately followed by closing the connection. -The reason field specifies why the client is resigning from the -session. It is encoded as an array of Compound Text strings. If the +The reason field specifies why the client is resigning +from the session. It is encoded as an array of Compound Text strings. If the resignation is expected by the user, there will typically be zero ARRAY8s here. But if the client encountered an unexpected fatal error, the error message (which might otherwise be printed on stderr @@ -848,12 +890,15 @@ protocols will not provide immediate notification of connection closure. - SetProperties [Client → SM] + +SetProperties [Client → SM] - properties: LISTofPROPERTY + properties: LISTofPROPERTY + -Sets the specified properties to the specified values. Existing +Sets the specified properties to the specified values. +Existing properties not specified in the Set­Properties message are unaffected. Some properties have predefined semantics. See section 11, "Predefined Properties." @@ -869,28 +914,34 @@ XSMP reserves all property names not beginning with an underscore for future use. - DeleteProperties [Client → SM] + +DeleteProperties [Client → SM] - property-names: LISTofARRAY8 + property-names: LISTofARRAY8 + Removes the named properties. - GetProperties [Client → SM] + +GetProperties [Client → SM] - Valid Responses: GetPropertiesReply + Valid Responses: GetPropertiesReply + Requests that the SM respond with the values of all the properties for this client. - GetPropertiesReply [Client ← SM] + +GetPropertiesReply [Client ← SM] - values: LISTofPROPERTY + values: LISTofPROPERTY + This message is sent in reply to a GetProperties -message and includes the values of all the properties. +message and includes the values of all the properties. -- cgit v1.2.3