# Presentation: 165834

## Process Manager Interface Narayan Desai, Rusty Lusk, Rick Bradshaw

## Outline

- PM Functionality
- PM Syntax
- PM Commands
- PM Datatypes
- PM Events
- PM Examples
- PM BNF
- PM Schema

## Process Manager Functionality

- Starts process groups, with specification of environments of application processes, either collectively or on a process-by-process basis
- Executable
- Arguments
- Environment variables
- User
- Resource limits
- Hosts for each process
- Working directory
- Queries the state of a running process group, returning some startup parameters
- Delivers signals to all processes in a process group
- Terminates a process group
- After process group exit, can wait on the group to collect exit codes and output.

## Process Manager Syntax

- The Process Manager uses the “less restricted syntax” style presented elsewhere
- Each message to it does three things:
- Describes a process group specification to be matched or created
- Conveys a command, with arguments
- Specifies an object to be returned

## Process Manager Commands

- CreateProcessGroup
- Takes as input a ProcessGroupSpecification object
- Returns a PGID
- GetProcessGroup
- Takes as input a ProcessGroup object which is matched against
- Returns a ProcessGroups container object containing requested fields from matched process group instances
- SignalProcessGroup
- Takes as input a Process Group object which is matched against
- Takes as argument a signal name and the scope of the signal (top-level processes or also forkees)
- Returns requested fields from the process groups signaled

## Process Manager Commands (cont.)

- KillProcessGroup
- Terminates matching process groups
- Best effort to really kill processes, which may require repeated signalling
- Returns the process groups matched
- WaitProcessGroup
- Returns exit code information and stream output from matching completed process groups
- Purges such information from the Process Manager state

## Process Manager Datatypes

- ProcessGroupSpecification
- Used as input to CreateProcessGroup
- ProcessGroup
- Used as matching description and returned description in other commands

## Process Manager Events

- Generated when a process group is successfully started:
-      <Event>
-        <Component>process-manager</Component>
-        <Message>ProcessStart</Message>
-        <Data>29</Data>
-      </Event>
- Generated when a process group terminates:
-      <Event>
-        <Component>process-manager</Component>
-        <Message>ProcessEnd</Message>
-        <Data>29</Data>
-      </Event>

## Process Manager Examples - 1

**<CreateProcessGroup>**
**  ****<ProcessGroupSpecification>**
**     ****<User>desai</User>**
**     ****<Size>8</Size>**
**     ****<Executable>/bin/false</Executable>**
**     ****<CWD>/tmp</CWD>**
**     ****<Diversions>**
**       ****<Diversion>**
**          ****<Range>6-7</Range>**
**          ****<Executable>/bin/true</Executable>**
**          ****<Environment>**
**            ****<Variable>**
**              ****<Name>LD_LIBRARY_PATH</Name>**
**              ****<Value>/local/lib</Value>**
**            ****</Variable>**
**          ****</Environment>**
**          ****<Arguments>**

## Process Manager Examples - 2

**             ****<Argument>-v</Argument>**
**          ****</Arguments>**
**      ****</Diversion>**
**    ****</Diversions>**
**    ****<HostSpecification>**
**      ****<Mode>Unordered</Mode>**
**      ****<Value>ccn1**
**                    ****ccn2**
**                    ****ccn3**
**                    ****ccn4**
**                    ****ccn5**
**                    ****ccn6**
**                    ****ccn7**
**                    ****ccn8**
**       ****</Value>**
**    ****</HostSpecification>**
**  ****</ProcessGroupSpecification>**
**</CreateProcessGroup>**

## Process Manager Examples - 3

- <GetProcessGroup>
-   <ProcessGroup>
-     <PGID>29</PGID>
-     <Processes>
-       <Process>
-          <Host match='false'/>
-       </Process>
-     </Processes>
-   </ProcessGroup>
- </GetProcessGroup>

## Process Manager Examples - 4

**ProcessGroups>**
**  ****<ProcessGroup>**
**     ****<PGID>29</PGID>**
**     ****<Processes>**
**        ****<Process>**
**           ****<Host>ccn1</Host>**
**        ****</Process>**
**        ****<Process>**
**           ****<Host>ccn2</Host>**
**        ****</Process>**
**        ****<Process>**
**           ****<Host>ccn3</Host>**
**        ****</Process>**
**        ****<Process>**
**           ****<Host>ccn4</Host>**
**        ****</Process>**
**        ****<Process>**
**           ****<Host>ccn5</Host>**
**        ****</Process>**
**        ****<Process>**
**           ****<Host>ccn6</Host>**
**        ****</Process>**
**        ****<Process>**
**           ****<Host>ccn7</Host>**
**        ****</Process>**
**        ****<Process>**
**           ****<Host>ccn8</Host>**
**        ****</Process>**
**     ****</Processes>**
**  ****</ProcessGroup>**
**</ProcessGroups>**

## Process Manager Examples - 5

**<GetProcessGroup>**
**  ****<ProcessGroup>**
**     ****<PGID>29</PGID>**
**     ****<Status match='false'/>**
**  ****</ProcessGroup>**
**</GetProcessGroup>**
**<ProcessGroups>**
**  ****<ProcessGroup>**
**     ****<PGID>29</PGID>**
**     ****<Status>Finished</Status>**
**  ****</ProcessGroup>**
**</ProcessGroups>**

## Process Manager Examples - 6

- <WaitProcessGroup>
-   <ProcessGroup>
-      <PGID>29</PGID>
-      <ExitStatus>
-        <Status>
-            <Code negate='true'>0</Code>
-            <Host match='false'/>
-        </Status>
-      </ExitStatus>
-      <Output>
-        <Stream>
-           <Name op='re'> stdout | stderr </name>
-           <Value match='false'/>
-        </Stream>
-      </Output>
-    </ProcessGroup>
- </WaitProcessGroup>

## Process Manager Examples - 7

**<ProcessGroups>**
**  ****<ProcessGroup>**
**    ****<PGID>29</PGID>**
**    ****<ExitStatus>**
**      ****<Status>**
**        ****<Host>ccn2</Host>**
**        ****<Code>1</Code</Host>**
**      ****</Status>**
**      ****<Status>**
**        ****<Host>ccn6</Host>**
**        ****<Code>255</Code>**
**      ****</Status>**
**   ****</ExitStatus>**
**   ****<Output>**
**      ****<Stream>**
**        ****<Name>stdout</Name>**

## Process Manager Examples - 8

**        ****<Value>process 0 on ccn1**
**process 1 on ccn2**
**process 2 on ccn3**
**process 3 on ccn4**
**process 4 on ccn5**
**process 5 on ccn6**
**process 6 on ccn7**
**process 7 on ccn8**
**</Value>**
**      ****</Stream>**
**      ****<Stream>**
**        ****<Name>stderr</Name>**
**        ****<Value/>**
**      ****</Stream>**
**    ****</Output>**
**  ****</ProcessGroup>**
**</ProcessGroups>**

## Process Manager BNF - 1

- [InMsg] ::= [CreateCommand] | [Query]
- [CreateCommand] ::= <CreateProcessGroup> [PGSpecification]
-                                      </CreateProcessGroup>
- [PGSpecification] ::= <ProcessGroupSpecification> [PGSattrs]
-                                    </ProcessGroupSpecification>
- [PGSattrs] ::= [PGSattr] | [PGSattr] [PGSattrs]
- [PGSattr] ::= <[FieldName]>[FieldValue]</[FieldName]>
- [Query] ::= <[ArgCmd] [Arguments]> [ProcessGroup] </[ArgCmd]> |
-                   <[Command]> [ProcessGroup] </[Command]>
- [Command] ::= KillProcessGroup | GetProcessGroup | WaitProcessGroup
- [ArgCmd] ::= SignalProcessGroup
- [Arguments] ::= [] | [Argument] | [Argument] [Arguments]
- [Argument] ::= [identifier]=[identifier]
- [ProcessGroup] ::= <ProcessGroup> [Fields] </ProcessGroup>
- [Fields] ::= [Field] | [Field] [Fields]|
-                   [MultiField] | [MultiField] [Fields]

## Process Manager BNF - 2

- [Field] ::= <[FieldName]> [FieldValue] </[FieldName]>
- [FieldName] ::= PGID|User|Size|Executable
- [FieldValue] ::= identifier
- [MultiField] ::= <[FieldGroup]> [MFields] </[FieldGroup]>
- [MFields] ::= [MField] | [MField] [MFields]
- [MField] ::= <[MFName] [Qualifiers]>[MFValue]</[MFName]>
- [Qualifiers] ::= [] | [Qualifier] [Qualifiers]
- [Qualifier] ::= [BooleanKey]=[BooleanValue]|
-                        [StringKey]=[StringValue]
- [BooleanKey] ::= 'negate' | 'match' | 'return'
- [BooleanValue] ::= 'true' | 'false'
- [StringKey] ::= 'op'
- [StringValue] ::= 'eq' | 'ne' | 'lt' | 'gt' | 'le' | 'ge' | 'range' | 're'
- [MFName] ::= HostSpec | Environment | Diversions
- [MFValue] :: identifier

## Process Manager Schema - 1

**<xsd:schema xmlns:xsd="**_[http://www.w3.org/2001/XMLSchema](http://www.w3.org/2001/XMLSchema)_**" xml:lang="en">**
**  ****<xsd:annotation>**
**    ****<xsd:documentation>**
**      ****Process Manager component schema**
**      ****SciDAC SSS project, 2004 **
**      ****Andrew Lusk alusk@mcs.anl.gov**
**      ****Narayan Desai desai@mcs.anl.gov**
**    ****</xsd:documentation>**
**  ****</xsd:annotation>**
**  ****<xsd:simpleType name='BooleanType'>**
**    ****<xsd:restriction base='xsd:string'>**
**      ****<xsd:pattern value='true|false'/>**
**    ****</xsd:restriction>**
**  ****</xsd:simpleType>**
**  ****<xsd:simpleType name='IntegerOps'>**
**    ****<xsd:restriction base='xsd:string'>**
**      ****<xsd:pattern value='eq|lt|gt|range|re'/>**
**    ****</xsd:restriction>**
**  ****</xsd:simpleType>**
**  ****<xsd:simpleType name='StringOps'>**
**    ****<xsd:restriction base='xsd:string'>**
**      ****<xsd:pattern value='eq|re'/>**
**    ****</xsd:restriction>**
**  ****</xsd:simpleType>**

## Process Manager Schema - 2

**  ****<xsd:simpleType name='Signals'>**
**    ****<xsd:restriction base='xsd:string'>**
**      ****<xsd:pattern**
**      ****value='ABRT|ALRM|BUS|CHLD|CLD|CONT|FPE|HUP|ILL|INT|IO|IOT|KILL|PIPE|POLL|PROF|PWR|QUIT|SEGV|STOP|SYS|TERM|TRAP|TSTP|TTIN|TTOU|URG|USR1|USR2|VTALRM|WINCH|XCPU|XFSZ'/>**
**    ****</xsd:restriction>**
**  ****</xsd:simpleType>**
**  ****<xsd:attributeGroup name='BaseLRSQuery'>**
**    ****<xsd:attribute name='match' type='BooleanType'/>**
**    ****<xsd:attribute name='negate' type='BooleanType'/>**
**    ****<xsd:attribute name='return' type='BooleanType'/>**
**  ****</xsd:attributeGroup>**
**  ****<xsd:complexType name='IntegerQueryAttribute'>**
**    ****<xsd:simpleContent>**
**      ****<xsd:extension base='xsd:integer'>**
**        ****<xsd:attributeGroup ref='BaseLRSQuery'/>**
**        ****<xsd:attribute name='op' type='IntegerOps'/>**
**      ****</xsd:extension>**
**    ****</xsd:simpleContent>**
**  ****</xsd:complexType>**
**  ****<xsd:complexType name='StringQueryAttribute'>**
**    ****<xsd:simpleContent>**

## Process Manager Schema - 3

**      ****<xsd:extension base='xsd:string'>**
**        ****<xsd:attributeGroup ref='BaseLRSQuery'/>**
**        ****<xsd:attribute name='op' type='IntegerOps'/>**
**      ****</xsd:extension>**
**    ****</xsd:simpleContent>**
**  ****</xsd:complexType>**
**  ****<xsd:complexType name='ProcessQueryType'>**
**    ****<xsd:sequence>**
**      ****<xsd:element name='Host' type='StringQueryAttribute' minOccurs='0'/>**
**      ****<xsd:element name='PID' type='StringQueryAttribute' minOccurs='0'/>**
**      ****<xsd:element name='Session' type='StringQueryAttribute' minOccurs='0'/>**
**    ****</xsd:sequence>**
**  ****</xsd:complexType>**
**  ****<xsd:complexType name='ProcessSet'>**
**    ****<xsd:choice minOccurs='1'>**
**      ****<xsd:element name='Process' type='ProcessQueryType'/>**
**    ****</xsd:choice>**
**  ****</xsd:complexType>**
**  **
**  ****<xsd:complexType name='ProcessGroupQuery'>**
**    ****<xsd:sequence>**
**      ****<xsd:element name='PGID' type='IntegerQueryAttribute' minOccurs='0'/>**

## Process Manager Schema - 4

**      ****<xsd:element name='Size' type='IntegerQueryAttribute' minOccurs='0'/>**
**      ****<xsd:element name='User' type='StringQueryAttribute' minOccurs='0'/>**
**      ****<xsd:element name='Status' type='StringQueryAttribute' minOccurs='0'/>**
**      ****<xsd:element name='Processes' type='ProcessSet' minOccurs='0'/>**
**    ****</xsd:sequence>**
**  ****</xsd:complexType>**
**  ****<xsd:complexType name='PGQuery'>**
**    ****<xsd:choice minOccurs='1' maxOccurs='unbounded'>**
**      ****<xsd:element name='ProcessGroup' type='ProcessGroupQuery'/>**
**    ****</xsd:choice>**
**  ****</xsd:complexType>**
**  ****<xsd:element name='GetProcessGroup' type='PGQuery'/>**
**  ****<xsd:element name='KillProcessGroup' type='PGQuery'/>**
**  ****<xsd:element name='WaitProcessGroup' type='PGQuery'/>**
**  ****<xsd:element name='SignalProcessGroup'>**
**    ****<xsd:complexType>**
**      ****<xsd:choice minOccurs='1' maxOccurs='unbounded'>**
**        ****<xsd:element name='ProcessGroup' type='ProcessGroupQuery'/>**
**      ****</xsd:choice>**
**      ****<xsd:attribute name='signal' type='Signals' use='required'/>**
**    ****</xsd:complexType>**
**  ****</xsd:element>**
**</xsd:schema> **

## Notes