From ceaa9a6af860b21125f6116bb8f88b1d9b495232 Mon Sep 17 00:00:00 2001 From: Philippe PITTOLI Date: Sat, 25 May 2024 05:57:46 +0200 Subject: [PATCH] Documentation change (s/stack/fifo/). --- src/dodb/storage/cached.cr | 2 +- src/dodb/storage/common.cr | 4 ++-- src/fifo.cr | 23 +++++++++++++---------- 3 files changed, 16 insertions(+), 13 deletions(-) diff --git a/src/dodb/storage/cached.cr b/src/dodb/storage/cached.cr index 546f6ff..684aadb 100644 --- a/src/dodb/storage/cached.cr +++ b/src/dodb/storage/cached.cr @@ -35,7 +35,7 @@ end # │   └── Corvet -> ../../data/0000000000 # ``` # -# WARNING: beware of the RAM use, see `DODB::Storage::Stacked` for a less memory-hungry option. +# WARNING: beware of the RAM use, see `DODB::Storage::Common` for a less memory-hungry option. class DODB::Storage::Cached(V) < DODB::Storage(V) @indexers = [] of Index(V) property data = Hash(Int32, V).new diff --git a/src/dodb/storage/common.cr b/src/dodb/storage/common.cr index cac6fe5..1efb384 100644 --- a/src/dodb/storage/common.cr +++ b/src/dodb/storage/common.cr @@ -12,7 +12,7 @@ # constantly ask for the same data over and over. # # ``` -# # Creates a DODB stacked database. +# # Creates a DODB database for common usage (a limited number of cached entries). # car_database = DODB::Storage::Common.new "/path/to/db" # # # Creates a (cached) index. @@ -37,7 +37,7 @@ class DODB::Storage::Common(V) < DODB::Storage::Cached(V) # In case the number of stored entries exceeds what is allowed, the least recently used entry is removed. property fifo : FIFO(Int32) - # Initializes the `StackedDataBase` with a maximum number of entries in the cache. + # Initializes the `DODB::Storage::Common` database with a maximum number of entries in the cache. def initialize(@directory_name : String, max_entries : UInt32) @fifo = FIFO(Int32).new max_entries Dir.mkdir_p data_path diff --git a/src/fifo.cr b/src/fifo.cr index e6684fb..4f3aaf5 100644 --- a/src/fifo.cr +++ b/src/fifo.cr @@ -1,25 +1,28 @@ # This class enables to keep track of used data. # -# Each time a value is pushed, it is put on top of a FIFO stack. -# Stack size is configurable, so in case the stack size exceeds what is allowed, +# Each time a value is added, it is put in a FIFO structure. +# Adding a value several times is considered as "using the value", +# so it is pushed back at the entry of the FIFO (as a new value). +# In case the number of entries exceeds what is allowed, # the least recently used value is removed. -# # ``` # fifo = FIFO(Int32).new 3 # Only 3 allowed entries. # -# pp! fifo << 1 # -> nil (there is still room in the stack) -# pp! fifo << 2 # -> nil (there is still room in the stack) +# pp! fifo << 1 # -> nil (there is still room in the FIFO structure) +# pp! fifo << 2 # -> nil (there is still room in the FIFO structure) # pp! fifo << 3 # -> nil (last entry without exceeding the allowed size) # pp! fifo << 4 # -> 1 (least recently used data) -# pp! fifo << 4 # -> nil (already in the stack) -# pp! fifo << 2 # -> nil (already in the stack) +# pp! fifo << 4 # -> nil (already in the structure) +# pp! fifo << 2 # -> nil (already in the structure) # pp! fifo << 5 # -> 3 (least recently used data) # ``` +# +# The number of entries in the FIFO structure is configurable. class FIFO(V) - # This array is used as a *stack*. + # This array is used as the *fifo structure*. property data : Array(V) - # Maximum allowed entries in the stack. + # Maximum allowed entries in the structure. property max_entries : UInt32 def initialize(@max_entries : UInt32) @@ -31,7 +34,7 @@ class FIFO(V) # WARNING: implementation is extremely simple (3 lines) and not designed to be highly efficient. def <<(v : V) : V? @data.select! { |x| v != x } # remove dups - @data.unshift v # push on top of the stack + @data.unshift v # push as the first value of the structure @data.pop if @data.size > @max_entries # remove least recently used entry if `@data` is too big end