cf01_notes.txt

cf01 -- C-Flat 01 Library Version 0.4.0


LICENSE

Copyright (c) 2023 Mac Stevens <stevensm@earthlink.net> <www.macstevens.net>

Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

Reference: https://opensource.org/licenses/ISC



DESCRIPTION

C-Flat is a project encompassing various programming tools, most of
which remain undeveloped as of March 2023.  cf00 is the version of 
C-flat implemented in C.  It is barely started.  For more information,
see commit e42fae1756c3e54786300e86e4895809bc39e62c.

cf01 is the version implemented in C++.  In 2021, the first tool of
practical use was implemented: Auto-Assert.  In 2023, the hash
consistency check was implemented.



AUTO ASSERT

Auto-Assert attempts to automate much of the following debugging cycle.
 1. Bug is detected.  Program crashes or produces wrong output, etc.
 2. Add debug code & assertions.
 3. Re-run.
 4. Add debug code & assertions.
 5. Re-run
 ...
 6. Bug is found.
 7. Bug is fixed.
 8. Add code to check bug is fixed.
 9. Re-run.
 10. Remove  debug code & assertions.
 11. Re-run.

Auto-Assert works as follows.  The programmer places assertions and
extra debug code using cf01 functions and/or macros.  These functions
and macros include hints indicating when such assertions and debug
code should be executed.  Some assertions are cheap and could be run
always, some are expensive and hence should be run rarely. The cf01 module
does the bookkeeping, keeping track of which assertions are run and
pass/fail status.  

When an assertion fails, cf01 stores some assertion information in a file
named cf01_jrnl.txt. When the program is re-started, cf01 reads this
file and enables more assertions and debug code, targeted to occur just prior to
the failing assertion.  Then the program is re-run, possibly triggering an
earlier assertion.  This process continues until the bug is found.

Ideally, the programmer's task becomes adding or modifying assertions and
debug code.  And cf01 handles the enabling and disabling of this 
additional code, which normally happens by simply re-running the application
without re-building.


Run 1
+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+
|                   |                   |                   |
Assert:PASS         Assert:PASS         Assert:FAIL         Assert


Run 2
+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+
|                   |    |    |    |    |                   |
Assert:PASS         |    |    |    |    Assert:FAIL         Assert
                    |    |    |    Assert:FAIL            
                    |    |    Assert:PASS
                    |    Assert:PASS
                    Assert:PASS


Run 3
                         Look for bug here  
                                \/
+----+----+----+----+----+----++++++----+----+----+----+----+----+----+----+----+
|                   |    |    ||||||    |                   |
Assert:PASS         |    |    ||||||    Assert:FAIL         Assert
                    |    |    |||||Assert:FAIL
                    |    |    ||||Assert:FAIL
                    |    |    |||Assert:FAIL
                    |    |    ||Assert:PASS
                    |    |    |Assert:PASS
                    |    |    Assert:PASS
                    |    Assert:PASS
                    Assert:PASS



HASH CONSISTENCY CHECK

The goal of the hash consistency check is to discover if a program does not
run consistently and where exactly the inconsistency is introduced.  One or
more hash functions must be supplied by the user.  Each hash function
should be a hash function of internal state, output, or any other data
that should be consistent from run to run.  Each hash function should have
no side effects -- no effect on internal state or result. 

At various locations in the code, the hash consistency check is called.
This causes the CF01 workspace to either a) most often, do nothing, or
b) call the supplied hash function and save the result.  It chooses
a) or b) according to several criteria.  It will call the hash function
 1. on a fixed schedule
 2. if sufficient time has elapsed without calling the hash function
 3. if the hash function was recorded on a previous run
 4. at additional times to isolate where the inconsistency is introduced

Example:

Run 1
+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+
|                   |                   |                   |
hc_chk:a4           hc_chk:31           hc_chk:97           hc_chk:f6

Run 2
+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+
|                   |                   |                   |
hc_chk:a4           hc_chk:31           hc_chk:97           hc_chk:dd:mismatch

Run 3
+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+
|                   |                   |    |    |    |    |
hc_chk:a4           hc_chk:31           |    |    |    |    hc_chk:37:mismatch
                                        |    |    |    hc_chk:27
                                        |    |    hc_chk:68
                                        |    hc_chk:52
                                        hc_chk:97

Run 4
+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+
|                   |                   |    |    |    |    |
hc_chk:a4           hc_chk:31           |    |    |    |    hc_chk:29:mismatch
                                        |    |    |    hc_chk:55:mismatch
                                        |    |    hc_chk:68
                                        |    hc_chk:52
                                        hc_chk:97

Run 5
+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+
|                   |                   |    |    ||||||    |
hc_chk:a4           hc_chk:31           |    |    ||||||    hc_chk:15:mismatch
                                        |    |    |||||hc_chk:48:mismatch
                                        |    |    ||||hc_chk:27
                                        |    |    |||hc_chk:79
                                        |    |    ||hc_chk:03
                                        |    |    |hc_chk:12
                                        |    |    hc_chk:68
                                        |    hc_chk:52
                                        hc_chk:97

                                        inconsistency introduced here
                                                     |  
Run 6                                                V
+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+
|                   |                   |    |    ||||||    |
hc_chk:a4           hc_chk:31           |    |    ||||||    hc_chk:43:mismatch
                                        |    |    |||||hc_chk:60:mismatch
                                        |    |    ||||hc_chk:42:mismatch
                                        |    |    |||hc_chk:74:mismatch
                                        |    |    ||hc_chk:03
                                        |    |    |hc_chk:12
                                        |    |    hc_chk:68
                                        |    hc_chk:52
                                        hc_chk:97



Where to place Hash Consistency Check:
 * Just after depth increment, hashing one or more fully initialized objects
 * Between modifications to an object state.

Where not to place Hash Consistency Check:
 * in a hash function
 * in initialization code.  Don't call a hash function on an uninitialized object.
 * in destructor code.  Don't call a hash function on an uninitialized object.
 * maybe(?) not in an invariant.  The idea is that if the object is in an invalid
   state, the invariant might catch the problem, but the hash function could crash.

The hash consistency check can also be used to detect an infinite loop. 
If the code has been running too long, the journal file (cf01_jrnl.txt)
will indicate which code is repeatedly running.





=== CYGWIN/GCC ===

BUILD TOOLS

  IDE: SlickEdit Version 11.0.0 Copyright 1988-2006 SlickEdit Inc.
       Technical Support Phone: 1 919.473.0070
       Technical Support Email: support@slickedit.com

  Cygwin v 3.1.7
       CYGWIN_NT-10.0 Lenovo-PC 3.1.7(0.340/5/3) 2020-08-22 17:48 x86_64 Cygwin
       https://www.cygwin.com/install.html

  Compiler:
       gcc (GCC) 10.2.0


  
BUILD

1. Start Cygwin
2. >cd cf01/gcc
3. >make --makefile=cf01.mak CFG=Debug
4. >make --makefile=cf01_test.mak CFG=Debug
(configurations = Debug, Release, or Profile)


TEST

1. Start Cygwin
2. >cd cf01/gcc/Debug
3. >./cf01_test.exe
4. >./cf01_test.exe
5. >./cf01_test.exe
6. >more cf01_jrnl.txt


WINDOWS DEPLOYMENT

In same directory as cf01_test.exe, place the following files:
  cyggcc_s-seh-1.dll
  cygstdc++-6.dll
  cygwin1.dll

These can be found in [CYGWIN INSTALLATION DIRECTORY]\cygwin\cygwin64\bin



=== WINDOWS/MICROSOFT VISUAL STUDIO ===

BUILD TOOLS

  Microsoft Visual Studio Professional 2022 (2)
    Version 17.6.5
    VisualStudio.17.Release/17.6.5+33829.357
    Microsoft .NET Framework
    Version 4.8.09037
    
  Visual C++ 2022   00476-80000-00000-AA260
    Microsoft Visual C++ 2022


BUILD

1. Open cf01\msvc\cf01.sln in Microsoft Visual Studio
2. Configuration: Debug/x64
3. Build cf01_test project


TEST
1. Open command termina.
2. >cd cf01\msvc\x64\Debug
3. >cf01_test.exe
4. >cf01_test.exe
5. >cf01_test.exe
6. >notepad cf01_jrnl.txt