Designing and Documenting Inter-Process Communication Links

I’ve touched on the subject of inter-process communication previously here and here, but now that I’m charged with doing a lot of this formally I wanted to discuss the process in more detail. I’m sharing this in outline form to keep the verbiage down and level of hierarchical organization up.

The following discussion attempts to outline everything that reasonably could be documented about an inter-process communication link. As a practical matter a shorthand will be worked out over time, especially for elements that are repeated often (e.g., a standard way of performing yaml-formatted JSON transfers). The methods associated with the standard practices should be documented somewhere, and then referenced when they are used for an individually documented connection.

  • General: Overall context description
    • Message Name: Name / Title of message
    • Description: Text description of message
    • Architecture Diagram: graphical representation that shows context and connections
    • Reason / Conditions: Context of why message is sent and conditions under which it happens; note whether operation is to send or receive
  • Source: Sending Entity
    • Sending System: Name, identifiers, addresses
    • Sending Process / Module / Procedure / Function: Specific process initiating communication
    • System Owner: Developer/Owner name, department/organization, email, phone, etc.
  • Message Creation Procedure: Describe how message gets created (e.g., populated from scratch, modified from another message, etc.)
    • Load Procedure: How elements are populated, ranged, formatted, etc.
    • Verification Procedure: How package is reviewed for correctness (might be analogous to CRC check, if applicable)
  • Payload: Message Content
    • Message Class: General type of message with respect to protocol and hardware (e.g., JSON, XML, IP packet, File Transfer, etc.)
    • Grammar: Structure of message, meaning of YAML/XML tags, header layout, and so on (e.g., YAML, XML, binary structure, text file, etc.)
    • Data Items: List of data items, variable names, types, sizes, and meanings (note language/platform dependency: C++ has hard data types and rules for data packing in structures and objects, JavaScript is potentially more flexible by platform)
      • Acceptable range of values: Important for certain data types in terms of size, content, and values
      • Header: Message header information (if accessible / controlled / modified by sender)
      • Body: Active payload
    • Message Size: Appropriate to messages that have a fixed structure and size (i.e., not applicable to flexibly formatted XML messages
  • Transfer Process: Receiving/Accessed Entity
    • Access Method: Means of logging in to or connecting with destination system (if applicable)
    • Permissions: passwords, usernames, access codes, lock/mutex methods
    • Reason: why destination system is accessed
  • Destination: Receiving Entity
    • Receiving System: Name, identifiers, addresses
    • Receiving Process / Module / Procedure / Function: Specific process initiating communication
    • System Owner: Developer/Owner name, department/organization, email, phone, etc.
  • Methodology: How it’s done
    • Procedure Description: List of steps followed
      • Default Steps (happy path): Basic steps (e.g., connect, open, lock, transfer/send, verify, unlock, close, disconnect)
      • Fail / Retry Procedures: What happens when connect/disconnect, open/close, lock/unlock, read/write operations fail in terms of detection (error codes), retry, error logging, and complete failure
      • Error Checking / Verification: How procedure determines whether different operations were performed correctly
        • Pack / Load / Unpack / Unload: check values/ranges, resulting structure format, etc.
        • Send / Receive: check connection / communication status
    • Side Effects / Logs: Describe logging activity and other side effects

This information is diagrammed below. (I need to add some arrows to show the steps taken but they can be inferred for now.)

The small diagram below shows the full context of one interface, which as a practical matter is a two-way communication where each direction could be fully documented as described above.

This entry was posted in Software and tagged , , , . Bookmark the permalink.

Leave a Reply