Trice Cache Specification (Draft)

Experimental implementation!

Preface

The trice insert and trice clean commands are parsing and modifying the source code files. Even this is a reasonable fast procedure, this could get time consuming on large projects, especially when using these commands as permanent pre-compile and post-compile steps. It is assumed, that usually between 2 compile steps not all project files are changed. The project files majority will stay unchanged despite the ID insertion and removal. This repeated parsing and modifying of unchanged source code is avoidable with the Trice cache technique. Also it could get anoying to recompile files all the time only because they got Trice IDs removed and inserted. With the Trice cache we get also a solution not to re-compile un-edited files as well.

Trice Cache Logic

When id.TriceCacheEnabled is true (applied -cache CLI switch) and the folder ~/.trice/cache exists, we have

• optionally a cleaned cache file ~/.trice/cache/cleaned/fullpath/file with mtime of IDs cleaned
• optionally an inserted cache file ~/.trice/cache/inserted/fullpath/file with mtime of IDs inserted
• fullpath/file with mtime of IDs cleaned OR IDs inserted OR last edit. When mtime of path/file is:
  • IDs cleaned:
    • On command trice c, nothing to do
    • On command trice i, copy, if existing, inserted cache file into fullpath/file. Otherwise process trice i and copy result into inserted cache file.
  • IDs inserted:
    • On command trice c, copy, if existing, cleaned cache file into fullpath/file. Otherwise process trice c and copy result into cleaned cache file.
    • On command trice i, nothing to do
  • last edit:
    • On command trice c, invalidate cache, process trice c and update cleaned cache file, file gets a new mtime, the mtime of IDs cleaned. _{On a following command trice i, file mtime is IDs cleaned, BUT the cache is invalid, so process trice i and update cache/inserted.}
    • On command trice i, invalidate cache, process trice i and update inserted cache file, file gets a new mtime, the mtime of IDs inserted. _{On a following command trice c, file mtime is IDs inserted, BUT the cache is invalid, so process trice c and update cache/cleaned.}

Remarks

• fullpath/file means /home/me/proj3/file for example. When copied to the cache, the real “fullpath” is there /home/me/.trice/cache/cleaned/home/me/proj3/file.

Should the .trice/cache be better located inside the project folder? What, if the user has several projects and several users on the same machine working on projects together? What about libraries containing trice code?

• The ~/.trice/cache folder should the Trice tool not create automatically in the users home folder $HOME. The existence of this folder is user controlled. The folder must exist. If several users work on the same project and some use the cache and some not - it is is possible this way, even build scripts are shared.
• The ~/.trice/cache folder should not go under revision control.
• A CLI switch -cache does enable/disable the Trice cache. Default is off.
• The user should consider what happens, if other pre-compile or post-compile steps are modifying files as well, before enabling the Trice cache.

Tests

Nr	Action	cCache	iCache	ID state	Edid state	Test function
0,1	0:clean	0:inval	0:inval	0:cleaned	X:any	Test_0_1_0000X_clean_on_invalid_cCache_invalid_iCache_cleaned_file
2,3	0:clean	0:inval	0:inval	1:inserted	X:any	Test_2_3_00011_clean_on_inalid_cCache_invalid_iCache_inserted_edited_file
4,5	0:clean	0:inval	1:valid	0:cleaned	X:any	Test_4_5_0010X_clean_on_invalid_cCache_valid_iCache_cleaned_file
6	0:clean	0:inval	1:valid	1:inserted	0:not	Test_6_00110_clean_on_invalid_cCache_valid_iCache_inserted_not_edited_file
7	0:clean	0:inval	1:valid	1:inserted	1:yes	Test_7_00111_clean_on_invalid_cCache_valid_iCache_inserted_edited_file
8	0:clean	1:valid	0:inval	0:cleaned	0:not	Test_8_01000_clean_on_valid_cCache_invalid_iCache_cleaned_not_edited_file
9	0:clean	1:valid	0:inval	0:cleaned	1:yes	Test_9_01001_clean_on_valid_cCache_invalid_iCache_cleaned_edited_file
10	0:clean	1:valid	0:inval	1:inserted	0:not	Test_10_01011_clean_on_valid_cCache_invalid_iCache_inserted_not_edited_file
11	0:clean	1:valid	0:inval	1:inserted	1:yes	Test_11_01011_clean_on_valid_cCache_invalid_iCache_inserted_edited_file
12	0:clean	1:valid	1:valid	0:cleaned	0:not	Test_12_01100_clean_on_valid_iCache_valid_cCache_clean_file_not_edited
13	0:clean	1:valid	1:valid	0:cleaned	1:yes	Test_13_01101_clean_on_valid_iCache_valid_cCache_clean_file_edited
14	0:clean	1:valid	1:valid	1:inserted	0:not	Test_14_01110_clean_on_valid_iCache_valid_cCache_inserted_file_not_edited
15	0:clean	1:valid	1:valid	1:inserted	1:yes	Test_15_01111_clean_on_valid_iCache_valid_cCache_inserted_file_edited
16,17	1:insert	0:inval	0:inval	0:cleaned	X:any	Test_16_17_1000X_insert_on_invalid_cCache_invalid_iCache_cleaned_file
18,19	1:insert	0:inval	0:inval	1:inserted	X:any	Test_18_19_1001X_insert_on_invalid_cCache_invalid_iCache_inserted_edited_file
20,21	1:insert	0:inval	1:valid	0:cleaned	X:any	Test_20_21_1010X_insert_on_invalid_cCache_valid_iCache_cleaned_file
22	1:insert	0:inval	1:valid	1:inserted	0:not	Test_22_10100_insert_on_invalid_cCache_valid_iCache_inserted_not_edited_file
23	1:insert	0:inval	1:valid	1:inserted	1:yes	Test_23_10101_insert_on_invalid_cCache_valid_iCache_inserted_edited_file
24	1:insert	1:valid	0:inval	0:cleaned	0:not	Test_24_11000_insert_on_valid_cCache_invalid_iCache_cleaned_not_edited_file
25	1:insert	1:valid	0:inval	0:cleaned	1:yes	Test_25_11001_insert_on_valid_cCache_invalid_iCache_cleaned_edited_file
26,27	1:insert	1:valid	0:inval	1:inserted	X:any	Test_26_27_1010X_insert_on_invalid_cCache_valid_iCache_cleaned_file
28	1:insert	1:valid	1:valid	0:cleaned	0:not	Test_28_11100_insert_on_valid_cCache_valid_iCache_cleaned_not_edited_file
29	1:insert	1:valid	1:valid	0:cleaned	1:yes	Test_29_11100_insert_on_valid_cCache_valid_iCache_cleaned_edited_file
30	1:insert	1:valid	1:valid	1:inserted	0:not	Test_30_11110_insert_on_valid_cCache_valid_iCache_inserted_not_edited_file
31	1:insert	1:valid	1:valid	1:inserted	1:yes	Test_31_11111_insert_on_valid_cCache_valid_iCache_inserted_edited_file

Issues

• When a trice i -cache && make && trice c -cache sequence is executed, it could happen with in an editor opened and unedited files containing Trice statements, that the editor does not refresh the file view again after the trice clean -cache command.
  • It looks like the Trice IDs were not cleaned.
  • Closing and opening the file again shows, that the Trice IDs are indeed cleaned.
  • If the file is edited then without refreshing the view, that means with the shown Trice IDs, this is no problem, because after saving the edited file, it gets processed anyway, so no data loss is possible.
  • An automatic view refresh (close & open) for the editor could help here. But how to do that in an universal way?
• A workaround is, at least for vsCode, to first run trice clean in the build script.
  • See trice/examples/G0B1_inst/build.sh for an implementation.