Mercurial > hg > orthanc-stone
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 |
| 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<>". |