Mercurial > hg > orthanc-stone
annotate OrthancStone/Resources/Conventions.txt @ 1515:b750b6eab453
sync
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Tue, 07 Jul 2020 20:52:35 +0200 |
parents | 244ad1e4e76a |
children |
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* |
1311
3d26447ddd28
warning fixes + doc + indentation + header files in cmake for VC++ sln browsing
Benjamin Golinvaux <bgo@osimis.io>
parents:
1299
diff
changeset
|
66 "std::shared_ptr<>"). We provide an implementation of std::unique_ptr for |
3d26447ddd28
warning fixes + doc + indentation + header files in cmake for VC++ sln browsing
Benjamin Golinvaux <bgo@osimis.io>
parents:
1299
diff
changeset
|
67 pre-C++11 compilers. |
1130 | 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 | |
1299
c38c89684d83
replacing std::auto_ptr by std::unique_ptr
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1133
diff
changeset
|
73 * Use "std::unique_ptr<>" if the goal is to internally store a pointer |
1130 | 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 | |
1133 | 80 clutter. The "loaders" and "data parts" objects must however |
81 be created as "boost::shared_ptr<>". | |
1130 | 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<>". |