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
|
|
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<>".
|