Diff: source/main.h

Revision:

24:62ca1f410862

Parent:

23:1976f83da84e

Child:

25:65e430b98cbe

diff -r 1976f83da84e -r 62ca1f410862 source/main.h
--- a/source/main.h	Fri Aug 04 21:10:31 2017 +0000
+++ b/source/main.h	Fri Aug 04 21:23:45 2017 +0000
@@ -9,11 +9,11 @@
 
 @section design_overview_sec Design Overview
 
-The application is designed around a concept serial execution of high level tasks called jobs.  The 'scheduler' library is responsible for maintaining job schedules and ensuring that only one job is executing at any given time.  The Scheduler library for details on how it works.
+The application is designed around the concept of serial execution of high level tasks called jobs.  The 'scheduler' library is responsible for maintaining job schedules and ensuring that only one job is executing at any given time.  See Scheduler library for details related to order of execution and scheduling.
 
-Each job is defined as a function that needs to be executed.  Currently the job function does not take any arguments.  It is planned that job may take a single argument of Scheduler::Appointment type.  Appointment provides all detailed data about job, its schedule and configurable per job instance parameters.
+Each job is defined as a function that needs to be executed.  Currently the job function does not take any arguments.  It is planned that job may take a single argument of Scheduler::Appointment type.  Appointment provides scheduler oriented details about the job and job instance specific configuration parameters.
 
-Each job has its own unique context that's defined by its dependency on application specific services.  Examples of application services:
+Each job has its own unique context that's defined by its dependency on application specific services.  Application service is a cohesively defined application feature.  Examples of application services:
 
 @li LCE is a lightweight collection engine proxy.  LCE provides interface for sending CoAP data to headend (HE).
 
@@ -23,17 +23,18 @@
 
 @li Scheduler is a service object from design level point of view.  Scheduler can be passed as a context dependency to jobs that need to manipulate schedules.
 
-If job is implemented as a C++ class, then its service references should be instance variables.  C++ reference is recommended, because ass services are always expected to be not NULL.
+In the modern application design internal application service is usually defined as an interface.  That interface then has production level implementation and may have test level mock implementations.  While Borsch is not specifically designed with this purpose in mind, it does not preclude the model.
 
-If job is implemented as a C module, then a separate initialize function is expected to set module level variables.
+Service objects are expected to be not NULL.  Failure to create a service object results in application termination as it results in cascading failure effect.
 
-In general failure to create a service object results in application termination as it results in cascading failure effect.
+If job is implemented as a C++ class, then its service references should be instance variables.  C++ 'reference' is recommended instead of pointer, because services are always expected to be not NULL.  If a particular service can be NULL, then recommendation does not apply.
+If job is implemented as a C module, then a separate initialize function is expected to set module level dependency variables.
 
 @subsection do_application_lifetime Application Lifetime
 
 Once service objects are created, job scheduler is started on the main application thread.  Main thread is then blocked by waiting for scheduler to quit.  Unless there is a job that explicitly requests scheduler termination, the main thread will never unblock. 
 
-If scheduler stops, then main thread proceeds to the final stage of the application.  At this stage it is guaranteed that no job will be started, because scheduler has been stopped.  Thus, environment is fully under main function control and drastic changes can be applied such as firmware upgrades.
+If scheduler stops, then main thread proceeds to the final stage of the application.  At this stage it is guaranteed that no job will be running and no new job can be started, because scheduler has been stopped.  Thus, environment is fully under the main() function control and drastic changes can be applied such as firmware upgrades.
 
 @subsection do_parallel_to_jobs Running of Other Parallel Threads
 
@@ -42,4 +43,5 @@
 For example, a receiving thread can be started for the life time of the socket.
 
 One consequence to consider is that creation of long running threads that go beyond job lifetime will make it more difficult to manage power consumption.  The recommended solution is to schedule another job through application scheduler from the job function itself. This way a single task at a time concept is not impacted and there is no concurrency complication.
+
 */ 
\ No newline at end of file