Mercurial > hg > orthanc-stone
view Resources/Conventions.txt @ 1314:9b126de2cde2 broker
Since the observer system now uses shared_ptr and many registrations are
done in the constructors, and since we cannot called shared_from_this() in
the constructors, it is mandatory to split construction from registration.
This has been done by making many ctors protected and replacing them
by factory methods that directly return shared_ptrs + added PostConstructor
method when base classes perform shared_from_this() calls too.
author | Benjamin Golinvaux <bgo@osimis.io> |
---|---|
date | Mon, 16 Mar 2020 11:19:50 +0100 |
parents | 3d26447ddd28 |
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<>".