doc/DESIGN

   1 Dinit Design Overview
   2 =====================
   3
   4 NOTE: This document is intended to provide an overview. Specifics are generally included as
   5       comments/documentation within source files.
   6
   7 Dinit's overall function is fairly straightforward but there are some considerations that cause
   8 its design to be more complicated than it might otherwise be.  The heart of the issue is that
   9 Dinit should not stall on I/O and its essential operation should never fail, which means that many
  10 code paths cannot perform memory allocation for example, and that log messages all go through a
  11 buffer.
  12
  13 The design is based around an event loop: events include process termination, signal reception,
  14 and I/O coming in from control sockets (used to issue service start/stop commands etc via
  15 dinitctl). The Dasynq library provides the backend event loop functionality; it is included
  16 with the Dinit source, but has a separate web page and documentation:
  17
  18     http://davmac.org/projects/dasynq/
  19
  20 Note that blocking actions are avoided: non-blocking I/O is used where possible; Dinit must
  21 remain responsive at all times.
  22
  23 In Dinit, service actions are often performed by setting "propagation" flags, inserting the
  24 service in a queue, and then processing the queues. Thus a lot of service actions are performed
  25 by first calling a function on a service and then draining the propagation queues. More
  26 information can be found in comments at the beginning of the includes/service.h header.
  27
  28 The logging subsystem is designed to log to two different sinks - typically, one is the console
  29 and one is the syslog facility, but other arrangements are possible. It uses a circular buffer
  30 for each output sink, and if the buffer becomes full it discards additional messages to avoid
  31 blocking (though it flags that this has occurred and later outputs a message to the sink).
  32 Services may acquire the console and in this case output is discarded (though it will of
  33 course continue to be logged to the other sink).
  34
  35 Control protocol handling uses a circular receive buffer, but allocates storage for outgoing
  36 packets dynamically. If allocation fails an "out of memory" flag is set and the connection is
  37 closed after writing an "out of memory" information packet.
  38
  39
  40 Services
  41 --------
  42
  43 There are presently four service types: internal, process, bgprocess and scripted. The latter
  44 three share the fact that they execute external processes and so naturally share some
  45 implementation. Specifically, the base service class is "service_record" - this directly
  46 supports "internal" services. The "base_process_service" class serves as a base class for
  47 the other three service types and provides common functionality.
  48
  49 Various functions in the service_record / base_process_service classes are virtual, so that
  50 they can be overridden by the subclasses.
  51
  52 All execution of child processes related to services currently goes through
  53 service_record::run_child_proc() (after forking).
  54
  55
  56 Source code organisation
  57 ------------------------
  58
  59 Most function comments and general documentation can be found in header files rather than in the
  60 corresponding source files.
  61
  62 dinit.cc - main event loop handling, command line parsing, general initialisation
  63
  64 service.cc, proc-service.cc, baseproc-service.cc -
  65     service logic (see service.h, proc-service.h)
  66
  67 run-child-proc.cc - contains service_record::run_child_proc(), used to run child processes.
  68
  69 load-service.cc - service loading
  70
  71 control.cc - control protocol handling
  72
  73 dinit-log.cc - logging subsystem
  74
  75 tests/ - various tests
  76
  77 The utility sources are:
  78
  79 dinitctl.cc - the control/status utility
  80 shutdown.cc - shutdown/halt/reboot utility
  81
  82
  83 Testing
  84 -------
  85
  86 The tests work by mocking out parts of Dinit, and some system calls, in order to isolate
  87 functional units. In the src/tests/test-includes directory are three mock headers. When compiling
  88 tests, the src/tests/includes directory is populated with (linked) copies of the standard headers
  89 from src/include, but with mocked headers taken from src/tests/test-includes instead.
  90
  91 Note that systems calls are not mocked directly, instead:
  92
  93  - system calls are wrapped in the bp_sys namespace, as defined in the baseproc-sys.h header;
  94  - for testing, the header is replaced with a mock header.
  95
  96 (This avoids problems that might arise from replacing important system calls, and in
  97 particular avoids interfering with the test harness itself).
  98
  99 It is important when writing new code in Dinit to avoid calling system calls directly, and to
 100 instead call the wrapper in bp_sys.
 101
 102
 103 Exception safety, error handling
 104 --------------------------------
 105
 106 In general operation Dinit methods should avoid throwing exceptions and be declared as 'noexcept',
 107 or otherwise be clearly documented as throwing exceptions. Errors should always be handled as
 108 gracefully as possible and should not prevent Dinit's continued operation. Particular care is
 109 needed for dynamic allocations: C++ style allocations (including adding elements to C++
 110 containers) will raise 'std::bad_alloc' if they cannot allocate memory, and this must be handled
 111 appropriately. Once it has started regular operation, Dinit must not terminate due to an error
 112 condition, even if the error is an allocation failure.