Mercurial > hg > orthanc-stone
view OrthancStone/Resources/Documentation/Conventions.txt @ 2174:2410a171ebfb
refactoring using DicomWebDataset and OrthancNativeDataset
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Tue, 22 Oct 2024 21:52:34 +0200 |
parents | b5417e377636 |
children |
line wrap: on
line source
Some notes about the lifetime of objects ======================================== Stone applications ------------------ A typical Stone application can be split in 3 parts: 1- The "loaders part" and the associated "IOracle", that communicate through "IMessage" objects. The lifetime of these objects is governed by the "IStoneContext". 2- The "data part" holds the data loaded by the "loaders part". The related objects must not be aware of the oracle, neither of the messages. It is up to the user application to store these objects. 3- The "viewport part" is based upon the "Scene2D" class. Multithreading -------------- * Stone makes the hypothesis that its objects live in a single thread. All the content of the "Framework" folder (with the exception of the "Oracle" stuff) must not use "boost::thread". * The "IOracleCommand" classes represent commands that must be executed asynchronously from the Stone thread. Their actual execution is done by the "IOracle". * In WebAssembly, the "IOracle" corresponds to the "html5.h" facilities (notably for the Fetch API). There is no mutex here, as JavaScript is inherently single-threaded. * In plain C++ applications, the "IOracle" corresponds to a FIFO queue of commands that are executed by a pool of threads. The Stone context holds a global mutex, that must be properly locked by the user application, and by the "IOracle" when it sends back messages to the Stone loaders (cf. class "IMessageEmitter"). * Multithreading is thus achieved by defining new oracle commands by subclassing "IOracleCommand", then by defining a way to execute them (cf. class "GenericCommandRunner"). References between objects -------------------------- * An object allocated on the heap must never store a reference/pointer to another object. * A class designed to be allocated only on the stack can store a reference/pointer to another object. Here is the list of such classes: - IMessage and its derived classes: All the messages are allocated on the stack. Pointers -------- * As we are targeting C++03 (for VS2008 and LSB compatibility), use "std::unique_ptr<>" and "boost::shared_ptr<>" (*not* "std::shared_ptr<>"). We provide an implementation of std::unique_ptr for pre-C++11 compilers. * The fact of transfering the ownership of one object to another must be tagged by naming the method "Acquire...()", and by providing a raw pointer. * Use "std::unique_ptr<>" if the goal is to internally store a pointer whose lifetime corresponds to the host object. * The use of "boost::weak_ptr<>" should be restricted to oracle/message handling. * The use of "boost::shared_ptr<>" should be minimized to avoid clutter. The "loaders" and "data parts" objects must however be created as "boost::shared_ptr<>". Global context -------------- * As the global Stone context can be created/destroyed by other languages than C++, we don't use a "boost:shared_ptr<>".