{"id":2111,"date":"2018-08-07T23:42:57","date_gmt":"2018-08-08T04:42:57","guid":{"rendered":"https:\/\/rpchurchill.com\/wordpress\/?p=2111"},"modified":"2018-08-08T17:50:32","modified_gmt":"2018-08-08T22:50:32","slug":"designing-and-documenting-inter-process-communication-links","status":"publish","type":"post","link":"https:\/\/rpchurchill.com\/wordpress\/posts\/2018\/08\/07\/designing-and-documenting-inter-process-communication-links\/","title":{"rendered":"Designing and Documenting Inter-Process Communication Links"},"content":{"rendered":"<p>I&#8217;ve touched on the subject of inter-process communication previously <a href=\"https:\/\/rpchurchill.com\/wordpress\/posts\/2017\/07\/13\/interface-analysis\/\">here<\/a> and <a href=\"https:\/\/rpchurchill.com\/wordpress\/posts\/2016\/05\/02\/methods-of-inter-process-communication-ive-employed\/\">here<\/a>, but now that I&#8217;m charged with doing a lot of this formally I wanted to discuss the process in more detail.  I&#8217;m sharing this in outline form to keep the verbiage down and level of hierarchical organization up.<\/p>\n<p>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.<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/www.rpchurchill.com\/p_resume\/bri\/Bric_L2_Sys_Arch_Test.jpg\" \/><\/p>\n<ul>\n<li><strong>General:<\/strong> Overall context description<\/li>\n<ul>\n<li><strong>Message Name:<\/strong> Name \/ Title of message<\/li>\n<li><strong>Description:<\/strong> Text description of message<\/li>\n<li><strong>Architecture Diagram:<\/strong> graphical representation that shows context and connections<\/li>\n<li><strong>Reason \/ Conditions:<\/strong> Context of why message is sent and conditions under which it happens; note whether operation is to send or receive<\/li>\n<\/ul>\n<li><strong>Source:<\/strong> Sending Entity<\/li>\n<ul>\n<li><strong>Sending System:<\/strong> Name, identifiers, addresses<\/li>\n<li><strong>Sending Process \/ Module \/ Procedure \/ Function:<\/strong> Specific process initiating communication<\/li>\n<li><strong>System Owner:<\/strong> Developer\/Owner name, department\/organization, email, phone, etc.<\/li>\n<\/ul>\n<li><strong>Message Creation Procedure:<\/strong> Describe how message gets created (e.g., populated from scratch, modified from another message, etc.)<\/li>\n<ul>\n<li><strong>Load Procedure:<\/strong> How elements are populated, ranged, formatted, etc.<\/li>\n<li><strong>Verification Procedure:<\/strong> How package is reviewed for correctness (might be analogous to CRC check, if applicable)<\/li>\n<\/ul>\n<li><strong>Payload:<\/strong> Message Content <\/li>\n<ul>\n<li><strong>Message Class:<\/strong> General type of message with respect to protocol and hardware (e.g., JSON, XML, IP packet, File Transfer, etc.)<\/li>\n<li><strong>Grammar:<\/strong> Structure of message, meaning of YAML\/XML tags, header layout, and so on (e.g., YAML, XML, binary structure, text file, etc.)<\/li>\n<li><strong>Data Items:<\/strong> List of data items, variable names, types, sizes, and meanings (note language\/platform dependency:<\/strong> C++ has hard data types and rules for data packing in structures and objects, JavaScript is potentially more flexible by platform)<\/li>\n<ul>\n<li><strong>Acceptable range of values:<\/strong> Important for certain data types in terms of size, content, and values<\/li>\n<li><strong>Header:<\/strong> Message header information (if accessible \/ controlled \/ modified by sender)<\/li>\n<li><strong>Body:<\/strong> Active payload<\/li>\n<\/ul>\n<li><strong>Message Size:<\/strong> Appropriate to messages that have a fixed structure and size (i.e., not applicable to flexibly formatted XML messages<\/li>\n<\/ul>\n<li><strong>Transfer Process:<\/strong> Receiving\/Accessed Entity<\/li>\n<ul>\n<li><strong>Access Method:<\/strong> Means of logging in to or connecting with destination system (if applicable)<\/li>\n<li><strong>Permissions:<\/strong> passwords, usernames, access codes, lock\/mutex methods<\/li>\n<li><strong>Reason:<\/strong> why destination system is accessed<\/li>\n<\/ul>\n<li><strong>Destination:<\/strong> Receiving Entity<\/li>\n<ul>\n<li><strong>Receiving System:<\/strong> Name, identifiers, addresses<\/li>\n<li><strong>Receiving Process \/ Module \/ Procedure \/ Function:<\/strong> Specific process initiating communication<\/li>\n<li><strong>System Owner:<\/strong> Developer\/Owner name, department\/organization, email, phone, etc.<\/li>\n<\/ul>\n<li><strong>Methodology:<\/strong> How it&#8217;s done<\/li>\n<ul>\n<li><strong>Procedure Description:<\/strong> List of steps followed<\/li>\n<ul>\n<li><strong>Default Steps (happy path):<\/strong> Basic steps (e.g., connect, open, lock, transfer\/send, verify, unlock, close, disconnect)<\/li>\n<li><strong>Fail \/ Retry Procedures:<\/strong> 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<\/li>\n<li><strong>Error Checking \/ Verification:<\/strong> How procedure determines whether different operations were performed correctly<\/li>\n<ul>\n<li><strong>Pack \/ Load \/ Unpack \/ Unload:<\/strong> check values\/ranges, resulting structure format, etc.<\/li>\n<li><strong>Send \/ Receive:<\/strong> check connection \/ communication status<\/li>\n<\/ul>\n<\/ul>\n<li><strong>Side Effects \/ Logs:<\/strong> Describe logging activity and other side effects<\/li>\n<\/ul>\n<\/ul>\n<p>This information is diagrammed below.  (I need to add some arrows to show the steps taken but they can be inferred for now.)<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/www.rpchurchill.com\/images\/articles\/20180627_Interface_Diagram.png\" width=\"400px\" title=\"right-click and view in higher resolution\" \/><\/p>\n<p>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.<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/www.rpchurchill.com\/images\/articles\/20180627_Interface_Context_1\" width=\"400px\" \/><\/p>\n","protected":false},"excerpt":{"rendered":"<p>I&#8217;ve touched on the subject of inter-process communication previously here and here, but now that I&#8217;m charged with doing a lot of this formally I wanted to discuss the process in more detail. I&#8217;m sharing this in outline form to &hellip; <a href=\"https:\/\/rpchurchill.com\/wordpress\/posts\/2018\/08\/07\/designing-and-documenting-inter-process-communication-links\/\">Continue reading <span class=\"meta-nav\">&rarr;<\/span><\/a><\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[5],"tags":[12,88,89,91],"_links":{"self":[{"href":"https:\/\/rpchurchill.com\/wordpress\/wp-json\/wp\/v2\/posts\/2111"}],"collection":[{"href":"https:\/\/rpchurchill.com\/wordpress\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/rpchurchill.com\/wordpress\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/rpchurchill.com\/wordpress\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/rpchurchill.com\/wordpress\/wp-json\/wp\/v2\/comments?post=2111"}],"version-history":[{"count":6,"href":"https:\/\/rpchurchill.com\/wordpress\/wp-json\/wp\/v2\/posts\/2111\/revisions"}],"predecessor-version":[{"id":2117,"href":"https:\/\/rpchurchill.com\/wordpress\/wp-json\/wp\/v2\/posts\/2111\/revisions\/2117"}],"wp:attachment":[{"href":"https:\/\/rpchurchill.com\/wordpress\/wp-json\/wp\/v2\/media?parent=2111"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/rpchurchill.com\/wordpress\/wp-json\/wp\/v2\/categories?post=2111"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/rpchurchill.com\/wordpress\/wp-json\/wp\/v2\/tags?post=2111"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}