Mercurial > hg > orthanc-stone
comparison Resources/Conventions.txt @ 1130:8c531253a434 broker
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<>". |