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

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