Mercurial > hg > orthanc-stone
annotate Resources/Conventions.txt @ 1308:adf234ecaa00 broker
Merge
author | Benjamin Golinvaux <bgo@osimis.io> |
---|---|
date | Wed, 04 Mar 2020 10:21:54 +0100 |
parents | c38c89684d83 |
children | 3d26447ddd28 |
rev | line source |
---|---|
1130 | 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 | |
1299
c38c89684d83
replacing std::auto_ptr by std::unique_ptr
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1133
diff
changeset
|
65 "std::unique_ptr<>" and "boost::shared_ptr<>" (*not* |
1130 | 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 | |
1299
c38c89684d83
replacing std::auto_ptr by std::unique_ptr
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1133
diff
changeset
|
72 * Use "std::unique_ptr<>" if the goal is to internally store a pointer |
1130 | 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 | |
1133 | 79 clutter. The "loaders" and "data parts" objects must however |
80 be created as "boost::shared_ptr<>". | |
1130 | 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<>". |