1HaikuDepot and Server Interactions 2================================== 3 4Introduction 5------------ 6 7This document aims to outline the general approach taken within the 8HaikuDepot application with regard to coordinating processes that relate 9to fetching and consuming data from remote systems. 10 11There are two main sources of remote data that are downloaded and 12consumed from network sources into the HaikuDepot desktop application; 13 14- Repository HPKR data from a Haiku mirror such as “HaikuPorts” 15- Meta-data related to packages from 16 `HaikuDepotServer <http://depot.haiku-os.org>`__ (HDS) such as icons, 17 localizations, ratings and so on. 18 19Process, ProcessNode and Coordinator 20------------------------------------ 21 22A *Process* (root class ``AbstractProcess``) is a class that takes 23responsibility for some aspect of pulling material down from a network 24source and processing it. 25 26A *ProcessNode* is a holder for a Process, but also takes responsibility 27for the following; 28 29- Maintaining the relationship between the Processes. For example, if 30 Process A needs to complete before Process B then the ProcessNode 31 would record this fact. It does this by storing *predecessor* and 32 *successor* ProcessNodes. 33- Starting the held Process in a newly spawned thread. 34- Stopping the held Process. 35 36A *Coordinator* holds a list of ProcessNodes. It will start, stop and 37cancel nodes as necessary such that, in an ideal case, the various 38ProcessNodes are completed in the correct order. 39 40The *ProcessCoordinatorFactory* is able to create Coordinators. 41 42Bulk Load Processes 43------------------- 44 45The following diagram shows the logical dependencies of the various 46Processes that are involved in refreshing the HPKR data from remote 47repositories and then loading data from the HDS system. 48 49.. figure:: images/processes.svg 50 :alt: Process Dependencies 51 52 Process Dependencies 53 54For example, the ``ServerRepositoryDataUpdateProcess`` must wait until 55the ``LocalRepositoryUpdateProcess`` has completed before it is able to 56be started. It is the reponsibility of the Coordinator to ensure that 57this sequencing is enforced. There are many instances of 58``ServerPkgDataUpdateProcess`` shown because there will be one launched 59for each of the Repositories for which data will be downloaded; 60“HaikuDepot” etc… 61 62Process / ProcessNode / Coordinator 63----------------------------------- 64 65The following diagram shows the relationship and interplay between the 66various objects that are involved in running a larger task. Only 67fictional Processes are shown to keep the diagram tidy. See above for 68the actual Processes. 69 70.. figure:: images/process-interplay.svg 71 :alt: Process Relationship and Interplay 72 73 Process Relationship and Interplay 74 75Dotted lines show associations between elements and red lines show 76interaction or data-flow. Green arrows here demonstratively show some 77dependency; Process C cannot start until A and B are completed. 78 79The MainWindow owns the Coordinator for the life-span of undertaking 80some larger task. 81 82Each Process is coupled with a ProcessNode and then the Coordinator has 83a list of the ProcessNodes-s. The Processes are generally writing to the 84local disk system (often with compressed files) to cache data (see 85``~/config/cache/HaikuDepot``) and also relay data into the ``Model`` 86object that maintains state for the HaikuDepot desktop application. 87 88The Processes communicate when they have finished to the Coordinator and 89it is at these events that the Coordinator is able to introspect the 90state of the Processes in order to know what to do next. 91 92The Coordinator also communicates with MainWindow. It communicates with 93the MainWindow in order to signal changes or progress in the overall 94larger task. The MainWindow also uses these events to discover when the 95Coordinator has completely finished. 96 97Failure 98------- 99 100A Process may fail or be stopped. If a Process fails or is stopped then 101successor Processes, or those that would have run after the failed 102process, are stopped so that they will not run. 103 104The Coordinator will still try to complete any other Processes that 105could still run or are running already. 106 107Upon the Coordinator completing, the Coordinator will signal to the 108MainWindow client the change in state and then the MainWindow will be 109able to identify that the Coordinator has completed, but that something 110has gone wrong along the way. 111 112Concurrency 113----------- 114 115It is important to note that Processes may run concurrently. The 116Processes’ are modelled by the Coordinator as a list rather than a tree. 117The dependencies are likely to form a tree or web of Processes that 118dictates the order of execution, but it is also quite possible to have 119multiple non-intersecting trees or webs such that Processes will execute 120independently. 121
