Mercurial > hg > orthanc-stone

comparison Resources/Conventions.txt @ 1130:8c531253a434 broker

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
conventions
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 06 Nov 2019 10:05:58 +0100
parents
children 0e3a3be313fd
comparison
equal deleted inserted replaced
1129:c3d4adf8bc70 1130:8c531253a434
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::auto_ptr<>" and "boost::shared_ptr<>" (*not*
66 "std::shared_ptr<>").
67
68 * The fact of transfering the ownership of one object to another must
69 be tagged by naming the method "Acquire...()", and by providing a
70 raw pointer.
71
72 * Use "std::auto_ptr<>" if the goal is to internally store a pointer
73 whose lifetime corresponds to the host object.
74
75 * The use of "boost::weak_ptr<>" should be restricted to
76 oracle/message handling.
77
78 * The use of "boost::shared_ptr<>" should be minimized to avoid
79 clutter. It is however mandatory to hold references to the "loaders"
80 and to the "data part" objects.
81
82
83 Global context
84 --------------
85
86 * As the global Stone context can be created/destroyed by other
87 languages than C++, we don't use a "boost:shared_ptr<>".