README.interprocess Some explanations about OpenCDN inter-process communications Topics: 1. Why it is needed 2. RRDM Core and Forked IPC mechanism 3. Node children and communications in between a) Node re-registration child (RRC) b) UDP probe answering child (UPAC) c) Producers and consumers 4. Origins 5. Dummy Convergence Layer 1. Why it is needed ---------------- If a unique entity is made of several concurrent processes, they need to share the same data, and some form of interprocess communication must be put in place. Otherwise, values which have been changed in one process's memory space, will not be available to another process. While a number of interprocess mechanism exists, they could be architecture-dependent, so we choose to rely only on mechanism offered by Perl. OpenCDN interprocess requirements are different for the entities defined, and different solutions have been adopted, so that a separate section is present for each. 2. RRDM Core and Forked IPC mechanism ---------------------------------- XML-RPC received by the RRDM are served by two different processes, named *Core* and *Forked*. Core is a sequential server, which listens at the RRDM base port, and serves requests which can be handled directly, such as registrations. Forked is a parallel server (which forks a sub-process for any request, from which its name), and handles Setup and Teardown requests, whose fulfillment involve other entities, and the relative response may take some time before to become available. The shared data are held by the Core process, and when the data must be read by the Forked process, the latter invokes a special XML-RPC method served by Core, named IPC, which makes the values available to Forked. Sometime Forked needs to perform some more complex processing with the shared data, or needs to write it: in such cases, Core's IPC method is invoked again, and a subroutine executed in the the Core memory space. See below for a pictorial sketch attempt. | | | | +--------|---------|-------------------------|--------|--------+ | RRDM | | +-------+ | | | | v v v | v v | | +-+--------+-+-------+-+-------+-+ | +-+-----+-+--------+-+ | | | |Register| |Publish| | IPC | | | | |SetUp| |Teardown| | | | | +--------+ +-------+ +-------+ | | | +-----+ +--------+ | | | | ^ ^ ^ | | | | | | | | | | | | | | | | | v v v | | | | | | | +--------------------+ | | | | | | | | Shared data | | +- + | | | | +--------------------+ | | | | | | CORE | | FORKED | | | +--------------------------------+ +--------------------+ | +--------------------------------------------------------------+ Peculiarities of Perl coding, allowed to write the Forked data access and remote invocation in a form which resembles local access and calls, and allows the two RRDM processes to be merged in only one, by setting the config variable $RRDMconfig::forked_addr to null. In fact, single value access is synthesized by the AUTOLOAD mechanism, which may (or may not) call the Core IPC method; also, subroutines invoked by Setup and Teardown contains an heading code, which may invoke itself in the Core instance via the IPC method, or execute locally. 3. Node children and communications in between ------------------------------------------- An OpenCDN node forks two children processes which runs in parallel, namely a re-registration child (RRC) and an UDP probe answering child (UPAC). These processes communicates with the main node thread by means of a DB_File tie, which lets the contents of a disk-based database, to appear as the content of a Perl hash. The values of shared variables are stored and retrieved to/from this hash, by associating the values to keys, named after the variables name. Here follows a table where key names and their use are listed. Key value DB_File used by -------------------------------------------------------------------------------- $prog Upstream Uri for us_URI_$node_address NodeLib.pm the given program Node.pm AuthToken XML-RPC Auth credential us_URI_$node_address NodeLib.pm Node.pm origin_$origin_address Origin.pm RTSPpassword RTSP Auth credential us_URI_$node_address NodeLib.pm Node.pm tra_$prog transport for us_URI_$node_address NodeLib.pm a given program Node.pm Dummy_Relay_$name simulates relay $name us_URI_$node_address Dummy.pm existence Please read below for some more explanation. 3.a Node re-registration child (RRC) -------------------------------- RRC periodically connects to RRDM, re-newing its registration data, and gets back these items: - OpenCDN name - re-registration delay - RTSP authentication password - XML-RPC authentication token OpenCDN name don't changes and is only informative, and the re-registration delay is internal to RRC. Instead, RTSP and XML-RPC authentication credentials must be communicated to the node main thread, by using as keys 'RTSPpassword' and'AuthToken'. 3.b UDP probe answering child (UPAC) -------------------------------- OpenCDN nodes can be probed by RRDM, in order to know if a given program URI is still relayed well. The relays are built by the node's Adaptation layer, and named by an algorithm which uses the program name, and the 'Upstream URI' for that program (i.e., the address from which this node receives it). After a new relay has been named and built, the Node main thread stores in a DB_file the value of the Upstream Uri, keyed by the program name. When a checking probe will later arrive for a given program, the UpstreamUri is retrieved from the DB_File by UPAC, the relay name re-constructed, and the relay inspected, to see if it is still working. 3.c Producers and consumers ----------------------- Here below follows a simple scheme showing who do write to the shared DB_File (the producers), and who reads form it (the consumers). At the producers side, RRC writes each time it contacts RRDM, while Node writes each time it receives (and fulfill) a DoRelay or NoRelay request. At the consumers side, UPAC reads each time it receives a checking UDP probe, and Node reads each time it must contact some other entity. +--------------+ | RRDM | +--------------+ ^ | Register | | DoRelay/NoRelay v v +-----+ +------+ | RRC | | Node | <------- Producers +-----+ +------+ | | RTSPpassword | | UpStream URI(Program) AuthToken | | v v (--------------) ( DB_File ) ( on disc ) (--------------) | | RTSPpassword | | UpStream URI(Program) AuthToken | | v v +------+ +------+ | Node | | UPAC | <------- Consumers +------+ +------+ | ^ v | Any method invocation UDP probe aiming to check toward other entities relaying of a given content 4. Origins ------- Origin entities have a Re-Publication Child (RPC), which behaves much like the RRC for nodes, and also uses a DB_File, for communicating to the Origin main thread the AuthToken needed for XML-RPC authentication. 5. Dummy Convergence Layer ----------------------- As explained in README.adaptation, Dummy.pm can be substitued to Meta.pm as a convergence layer, for development purposes, avoiding the requirement of having a streaming server technology running on board. As such, Dummy.pm cannot correctly answer to UDP probes which ask for the proper functioning of a local relay. In order to mimic an underlying (non-existent) adaptation layer, Dummy.pm remembers if it simulated the creation of a relay previously, by using of the Dummy_Relay_$name key in the us_URI_$node_address DB_File.