oxedyne/fe2o3 — fe2o3_o3db_sync/ref/html/zone

oxedyne/fe2o3/fe2o3_o3db_sync/ref/html/zone_config.html

7.3 KiB, 1 run

created by r1870400018:678, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1	<!DOCTYPE html>
2	<html>
3	<head>
4	<style>
5	/* Split the screen in half */
6	.split {
7	height: 100%;
8	width: 50%;
9	position: fixed;
10	z-index: 1;
11	top: 0;
12	overflow-x: hidden;
13	padding-top: 20px;
14	}
15
16	/* Control the left side */
17	.left {
18	left: 0;
19	color: white;
20	background-color: black;
21	margin-left: 50 px;
22	}
23
24	/* Control the right side */
25	.right {
26	right: 0;
27	background-color: white;
28	}
29
30	</style>
31	</head>
32	<body>
33	<div class="split right">
34	<h1>O3db from 10,000 ft</h1>
35	<img width=100%; src="../svg/zone_config.svg" />
36	</div>
37	<div class="split left">
38	<h1>Starting and changing Ozone</h1>
39	<p>The most basic database settings are controlled via a Config structure. This is initialised in three possible ways:</p>
40	<ol>
41	<li>by being provided directly to the instance,</li>
42	<li>by providing the path to a text file in Jason's Data And Type (jdat) format,</li>
43	<li>by opting for a default configuration.</li>
44	</ol>
45	<p>The O3db instance must then be manually started by the user, invoking the creation of a supervisor bot.</p>
46	<h2>Initialisation</h2>
47	<p>Since the supervisor is responsible for starting and stopping bots while the database is running, it is also given the task of coordinating the initialisation process:</p>
48	<ol>
49	<li>The supervisor starts all required bots, and panics if there is a problem. This is the last point at which an Ozone database should panic, as all subsequent errors should be reported to the log file. Automated garbage collection is initially inactive.</li>
50	<li>All bots are initialised with the (mostly validated) configuration. The zone bots wait for notification of their directories. The config bot validates any configuration zone override information during its own initialisation, and notifies zone bots of their directories.</li>
51	<li>The zone bots then ensure that their directories can be created (if not, defaulting to the root directory) and survey all existing files.</li>
52	<li>The zone bots then use their init and cache bots to fill the caches using file data, recreating absent or incomplete index files if necessary.</li>
53	<li>The database itself contains a user register, which the supervisor now proceeds to read and distribute to the server and all cbots.</li>
54	<li>Automated garbage collection is activated.</li>
55	</ol>
56	<h2>Configuration</h2>
57	<p>The configuration can be changed via the configuration file, or API messages. The solo config bot (cfgbot) checks the file on a regular basis. When there is a change, it reads the file, decodes the text to a ConfigDat struct and compares it with its current copy of ConfigDat.</p>
58	<p>The configuration specifies the number of zones, and the path to the database container directory. This path can be absolute or relative to the caller's working directory. By default, as an example, a three zone database has zone directories located at root/003_zone/, that is, root/003_zone/zone_001, root/003_zone/zone_002 and root/003_zone/zone_003. However, non-default container directories for each zone can also be specified. In our example, we might want zone 2 to be located inside directory A, in which case the zone directory path would become A/003_zone/zone_002.</p>
59	</ol>
60	<h3>Change to one or more existing zone container directories</h3>
61	<p> When there is a change to these container directories and no change to the number of zones, the system must pause all activity and simply move the directories:</p>
62	<ol>
63	<li>The cfgbot identifies which zone directories must be moved and sends the information to the supervisor.</li>
64	<li>The supervisor creates the new container directories if they do not exist.
65	<li>The supervisor sends a <em>MoveDirectory</em> message including an updated configuration and responder channels to all bots in each affected zone. The bots pause and messages may continue to accumulate in their buffers.</li>
66	<li>The zbots listen for all their worker bots confirm that they are idle.</li>
67	<li>The zbots then move the directories.</li>
68	<li>The zbots confirm the move to the supervisor and the worker bots, which resume operations.</li>
69	</ol>
70	<h3>Change in number of zones -- rezoning</h3>
71	<p>Since all data is sharded in the first instance across zones according to key hashes, a change in the number of zones requires all existing data to be reallocated across a new set of zone directories. This requires the full participation of the existing worker bots, meaning all incoming messages at the API level must be paused. We cannot easily repurpose existing worker bots to perform this reallocation -- a new set of bots must be created. The whole process begins when the cfgbot detects the change:<p>
72	<ol>
73	<li>If the new number of zones is valid and consistent in the ConfigDat, the cfgbot sends the new zone arrangement to the supervisor.</li>
74	<li>The supervisor sends a Rezone message to the sbot, including an updated configuration and responder, in order to start choking the worker bots of new incoming messages. Messages may continue to accumulate in the sbot channels.</li>
75	<li>The supervisor creates the new container directories if they do not exist.</li>
76	<li>The supervisor creates a new set of channels, bots and handles for the new zones.</li>
77	<li>The supervisor waits for confirmation that the sbot has paused all database inputs.</li>
78	<li>The supervisor waits for all existing worker bot message queue lengths to remain at zero for a sustained period.</li>
79	<li>The supervisor sends a Rezone message to the <em>existing</em> cbots, including responders and the list of new wbot channels, instructing them to loop through their caches and write values to the new zones. When a cache contains only the location, the cbot activates an existing rbot to read the data, but when a value is available, it can be sent immediately to the appropropriate wbot.</li>
80	<li>The supervisor waits for all existing cbots to notify completion.</li>
81	<li>The supervisor all bots for existing zones, and waits for confirmation.</li>
82	<li>The supervisor sends the new channels to the sbot, instructing it to resume operations.</li>
83	</ol>
84	<h3>Change in number of cbots per zone -- recaching</h3>
85	<p>Recaching is simpler than rezoning since it does not involve any change to directories and files. In each zone, the existing cbots must reallocate all their contents to the new cbots. When the cfgbot detects the relevant change:
86	<ol>
87	<li>If the new number of cbots per zone is valid, the cfgbot sends a Recache message to the supervisor.</li>
88	<li>The supervisor sends a Recache message, including the new number of cbots per zone and responders, to all rbots and wbots. This pauses the bots and messages may continue to accumulate in their buffers.</li>
89	<li>The supervisor creates a new set of cbots for each zone.</li>
90	<li>The supervisor advises all other relevant bots of the new cbots.</li>
91	<li>The supervisor waits until the message queue lengths for the existing cbots remain at zero for a sustained period.</li>
92	<li>The supervisor then instructs existing cbots to loop through their caches and send the data to the new cbots. There is no involvement from any other worker bots.</li>
93	<li>The supervisor waits for all cbots to indicate completion.</li>
94	<li>The supervisor waits for all other relevant bots to confirm their knowledge of the new cbots.</li>
95	<li>The supervisor issues a Resume message to the rbots and wbots.</li>
96	</ol>
97	</div>
98	</body>
99	</html>