Mercurial > hg > orthanc-stone

comparison OrthancStone/Resources/Documentation/Conventions.txt @ 1586:b5417e377636

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
reorganization
author Sebastien Jodogne <s.jodogne@gmail.com>
date Thu, 22 Oct 2020 16:17:10 +0200
parents OrthancStone/Docs/Conventions.txt@d1806b4e4839
children
comparison
equal deleted inserted replaced
1585:94edbfa64c97 1586:b5417e377636
1
2 Some notes about the lifetime of objects
3 ========================================
4
5 Stone applications
6 ------------------
7
8 A typical Stone application can be split in 3 parts:
9
10 1- The "loaders part" and the associated "IOracle", that communicate
11 through "IMessage" objects. The lifetime of these objects is
12 governed by the "IStoneContext".
13
14 2- The "data part" holds the data loaded by the "loaders part". The
15 related objects must not be aware of the oracle, neither of the
16 messages. It is up to the user application to store these objects.
17
18 3- The "viewport part" is based upon the "Scene2D" class.
19
20
21 Multithreading
22 --------------
23
24 * Stone makes the hypothesis that its objects live in a single thread.
25 All the content of the "Framework" folder (with the exception of
26 the "Oracle" stuff) must not use "boost::thread".
27
28 * The "IOracleCommand" classes represent commands that must be
29 executed asynchronously from the Stone thread. Their actual
30 execution is done by the "IOracle".
31
32 * In WebAssembly, the "IOracle" corresponds to the "html5.h"
33 facilities (notably for the Fetch API). There is no mutex here, as
34 JavaScript is inherently single-threaded.
35
36 * In plain C++ applications, the "IOracle" corresponds to a FIFO queue
37 of commands that are executed by a pool of threads. The Stone
38 context holds a global mutex, that must be properly locked by the
39 user application, and by the "IOracle" when it sends back messages
40 to the Stone loaders (cf. class "IMessageEmitter").
41
42 * Multithreading is thus achieved by defining new oracle commands by
43 subclassing "IOracleCommand", then by defining a way to execute them
44 (cf. class "GenericCommandRunner").
45
46
47 References between objects
48 --------------------------
49
50 * An object allocated on the heap must never store a reference/pointer
51 to another object.
52
53 * A class designed to be allocated only on the stack can store a
54 reference/pointer to another object. Here is the list of
55 such classes:
56
57 - IMessage and its derived classes: All the messages are allocated
58 on the stack.
59
60
61 Pointers
62 --------
63
64 * As we are targeting C++03 (for VS2008 and LSB compatibility), use
65 "std::unique_ptr<>" and "boost::shared_ptr<>" (*not*
66 "std::shared_ptr<>"). We provide an implementation of std::unique_ptr for
67 pre-C++11 compilers.
68
69 * The fact of transfering the ownership of one object to another must
70 be tagged by naming the method "Acquire...()", and by providing a
71 raw pointer.
72
73 * Use "std::unique_ptr<>" if the goal is to internally store a pointer
74 whose lifetime corresponds to the host object.
75
76 * The use of "boost::weak_ptr<>" should be restricted to
77 oracle/message handling.
78
79 * The use of "boost::shared_ptr<>" should be minimized to avoid
80 clutter. The "loaders" and "data parts" objects must however
81 be created as "boost::shared_ptr<>".
82
83
84 Global context
85 --------------
86
87 * As the global Stone context can be created/destroyed by other
88 languages than C++, we don't use a "boost:shared_ptr<>".