blib/lib/AmberDB/Base/Ramdisk.pm untested

filter: Statementstmt 0.0% 0 / 561 Branchbran 0.0% 0 / 354 Conditioncond 0.0% 0 / 427 MC/DCmcdc 0.0% 0 / 240 Subroutinesub 0.0% 0 / 30 Podpod 0.0% 0 / 24 totaltotal 0.0% 0 / 1636 CC 178 SCAR 67.4
CC
178
Cov
0%
ramdisk_sync
2070.0
ramdisk_setup
1722.0
ramdisk_preload
240.0
CRAP 843.8
1 package AmberDB::Base::Ramdisk;
2  
3 use 5.016;
4 use warnings;
5 use Carp qw(croak cluck);
6 use Cwd qw(abs_path);
7 use Digest::MD5 qw(md5_hex);
8  
9 our $VERSION = '5.26.6';
10 my $CREATED = '2026-08-11';
11  
12 our %RAMDISK_TIERS = (
13 '0' => 0,
14 'none' => 0,
15 'off' => 0,
16 'disk' => 0,
17 'disabled' => 0,
18  
19 '1' => 1,
20 'index' => 1,
21 'indexes' => 1,
22 'indices' => 1,
23 'hybrid' => 1,
24  
25 '2' => 2,
26 'dual' => 2,
27 'full' => 2,
28 'all' => 2,
29 'mirror' => 2,
30 'mirrored' => 2,
31  
32 '3' => 3,
33 'temp' => 3,
34 'temporary' => 3,
35 'volatile' => 3,
36 'ephemeral' => 3,
37 'ram_only' => 3,
38 'memory_only' => 3,
39  
40 '4' => 4,
41 'async' => 4,
42 'sync' => 4,
43 'delay' => 4,
44 'delayed' => 4,
45 'write_behind' => 4,
46 'writeback' => 4,
47 );
48  
49 our %RM_DIR = (
50 windows => "R:",
51 linux => "/dev/shm",
52 macos => "/Volumes",
53 );
54  
55 sub _normalize_ramdisk_tier {
56 my ( $self, $val ) = @_;
57 return 0 unless defined $val && length $val;
58 my $key = lc("$val");
59 $key =~ s/^\s+|\s+$//g;
60 return exists $RAMDISK_TIERS{$key} ? $RAMDISK_TIERS{$key} : ( $key =~ /^\d+$/ ? int($key) : 0 );
61 }
62  
63 # ============================================================================
64 # AmberDB Native .db and .inx RAM-Disk (Linux tmpfs / macOS APFS / Windows ImDisk) Engine
65 # Purely dedicated to physical RAM-Disk file-based acceleration
66 # ============================================================================
67  
68 # Resolves root directory for ramdisk storage (typically mounted as tmpfs / APFS / ImDisk)
69 sub ramdisk_dir {
70 my ($self) = @_;
71 return "" unless $self->ramdisk_is_mounted();
72 return $self->path('ramdisk_dir') // "";
73 }
74  
75 # Backwards compatibility path accessors (returns empty string if RAM-disk is unmounted)
76 sub ramdisk_tbl_dir {
77 my ($self) = @_;
78 return "" unless $self->ramdisk_is_mounted();
79 return $self->{_path}->{table_rdir} // $self->path('table_rdir') // "";
80 }
81  
82 sub ramdisk_lock_dir {
83 my ($self) = @_;
84 return "" unless $self->ramdisk_is_mounted();
85 return $self->{_path}->{lock_dir} || $self->path('lock_dir') || "";
86 }
87  
88 sub ramdisk_schema_dir {
89 my ($self) = @_;
90 return "" unless $self->ramdisk_is_mounted();
91 return $self->{_path}->{schema_rdir} // $self->path('schema_rdir') // "";
92 }
93  
94 sub ramdisk_session_dir {
95 my ($self) = @_;
96 return "" unless $self->ramdisk_is_mounted();
97 return $self->{_path}->{session_dir} || $self->path('session_dir') || "";
98 }
99  
100 # Returns 1 if RAM-disk is mounted and ready, 0 otherwise.
101 # In list context, returns ($is_mounted, $mount_desc, $active_ramdisk_dir, $sys_info).
102 # Checks cache('ramdisk', 'is_mounted'); if undef, calls ramdisk_setup to initialize.
103 # ------------------------------------------------
104 sub ramdisk_is_mounted {
105 my ( $self ) = @_;
106  
107 my $is_mounted = $self->get_cache( 'ramdisk', 'is_mounted' );
108  
109 # run ramdisk_setup
110 if ( !defined $is_mounted ) {
111 my $info = $self->ramdisk_setup();
112 $is_mounted = $info->{is_mounted};
113 }
114 return $is_mounted;
115 }
116  
117 # my $info = $adb->ramdisk_setup([$tableid], [%opts]);
118 # Sets up RAM-disk paths, mount diagnostics, and creates subdirectories in RAM-disk.
119 # Evaluates %RM_DIR and database name isolation.
120 # When unmounted, sets ramdisk_dir and all *_rdir to empty strings (strict zero-fallback).
121 # Sets is_mounted (1 or 0) and stores mount status.
122 # If optional $tableid is provided and mounted, preloads/ensures the table on RAM-disk.
123 # ------------------------------------------------
124 sub ramdisk_setup {
125 my ( $self, @args ) = @_;
126  
127 my $tableid;
128 my %opts;
129  
130 if ( @args == 1 && ref( $args[0] ) eq 'HASH' ) {
131 %opts = %{ $args[0] };
132 }
133 elsif ( @args % 2 != 0 ) {
134 $tableid = shift @args;
135 %opts = @args;
136 }
137 elsif (@args) {
138 %opts = @args;
139 }
140  
141 my $dbase_dir = $self->path('dbase_dir') || ".";
142 my $os = ( $^O eq 'MSWin32' || $^O eq 'msys' || $^O eq 'cygwin' ) ? 'windows'
143 : ( $^O eq 'darwin' ) ? 'macos'
144 : 'linux';
145 my $bin_dir = "$dbase_dir/../bin";
146 my $helper_pl = "$bin_dir/amberdb_cli.pl";
147 my $disk_size = $self->config('ramdisk_size') // '512M';
148 my $sys = {
149 os => $os,
150 script_pl => $helper_pl,
151 script_bat => "$bin_dir/setup_windows.bat",
152 instructions => $os eq 'windows'
153 ? "Run as Administrator: bin\\setup_windows.bat start $disk_size"
154 : "Linux (/dev/shm) and macOS (/Volumes) use in-memory RAM storage automatically",
155 };
156  
157 my $dbname = $self->{_connect}->{database};
158 $dbname = '' if !defined $dbname || $dbname eq '.' || $dbname eq 'dbstore';
159  
160 my $is_mounted = 0;
161 my $mount_desc = "Local Storage (No RAM-disk active)";
162 my $ramdisk_dir = '';
163  
164 # 1. Test environment simulation override
165 if ( defined $ENV{AMBERDB_TEST_RAMDISK} && $ENV{AMBERDB_TEST_RAMDISK} eq '0' ) {
166 $ramdisk_dir = '';
167 $is_mounted = 0;
168 $mount_desc = "Local Storage (No RAM-disk active)";
169 }
170 elsif ( $ENV{AMBERDB_TEST_RAMDISK} ) {
171 if ( $ENV{AMBERDB_TEST_RAMDISK} ne '1' ) {
172 $ramdisk_dir = $ENV{AMBERDB_TEST_RAMDISK};
173 }
174 elsif ( $opts{ramdisk_dir} || $self->path('ramdisk_dir') ) {
175 $ramdisk_dir = $opts{ramdisk_dir} || $self->path('ramdisk_dir');
176 }
177 else {
178 my $test_target = ( length $dbname && $dbname ne '.' && $dbname ne 'dbstore' )
179 ? "amberdb_$dbname"
180 : "amberdb_test";
181 my $rm_base = $opts{ramdisk_base};
182 my $chk_base = $rm_base;
183 $chk_base .= '/' if defined $chk_base && $os eq 'windows' && $chk_base =~ /^[a-zA-Z]:$/;
184 if ( defined $rm_base && length $rm_base && -d $chk_base ) {
185 $ramdisk_dir = "$rm_base/$test_target";
186 }
187 else {
188 $ramdisk_dir = File::Spec->catdir( File::Spec->tmpdir(), $test_target );
189 }
190 }
191 if ( length $ramdisk_dir ) {
192 $ramdisk_dir =~ s{[\\/]+$}{};
193 $is_mounted = 1;
194 $mount_desc = "Test RAM-Disk Emulation ($ramdisk_dir)";
195 }
196 else {
197 $is_mounted = 0;
198 $mount_desc = "Local Storage (No RAM-disk active)";
199 }
200 }
201 # 2. Database name check: if dbname is empty/missing, direct fallback to local storage
202 elsif ( !length $dbname ) {
203 $ramdisk_dir = '';
204 $is_mounted = 0;
205 $mount_desc = "Local Storage (No RAM-disk active)";
206 }
207 # 3. Check explicit ramdisk_dir or OS RAM-disk mount base from %RM_DIR
208 else {
209 my $rm_base = $opts{ramdisk_base} || $RM_DIR{$os};
210 my $configured_rdir = $opts{ramdisk_dir} || $self->path('ramdisk_dir');
211  
212 # Helper to verify if a candidate path actually resides on the OS RAM-disk
213 my $_path_is_ram = sub {
214 my ($p) = @_;
215 return 0 unless defined $p && length $p;
216 if ( $os eq 'windows' ) {
217 my $chk = $p;
218 $chk .= '/' if $chk =~ /^[a-zA-Z]:$/;
219 return ( $p =~ /^[rR]:/i || $p =~ m{^/[rR]/}i ) && -d $chk;
220 }
221 elsif ( $os eq 'linux' ) {
222 return ( $p =~ m{^/dev/shm(?:/|$)} ) && -d $p;
223 }
224 elsif ( $os eq 'macos' ) {
225 return ( $p =~ m{^/Volumes/} ) && -d $p;
226 }
227 return 0;
228 };
229  
230 if ( length $configured_rdir && $configured_rdir ne $dbase_dir ) {
231 if ( $_path_is_ram->($configured_rdir) ) {
232 $ramdisk_dir = $configured_rdir;
233 $is_mounted = 1;
234 }
235 }
236 elsif ( defined $rm_base && length $rm_base ) {
237 my $rm_base_check = $rm_base;
238 $rm_base_check .= '/' if $os eq 'windows' && $rm_base_check =~ /^[a-zA-Z]:$/;
239 if ( $os eq 'macos' ) {
240 # On macOS, /Volumes is root-owned and holds mount points.
241 # An APFS/HFS+ RAM-disk is only considered mounted if the volume
242 # directory already exists and is writable.
243 my $target_rdir = "$rm_base/amberdb_$dbname";
244 if ( -d $target_rdir && -w $target_rdir ) {
245 $ramdisk_dir = $target_rdir;
246 $is_mounted = 1;
247 }
248 }
249 elsif ( -d $rm_base_check ) {
250 $ramdisk_dir = "$rm_base/amberdb_$dbname";
251 $is_mounted = 1;
252 }
253 }
254  
255 if ($is_mounted) {
256 $ramdisk_dir =~ s{[\\/]+$}{};
257 $mount_desc = ( $os eq 'windows' ) ? "ImDisk RAM-Disk on R: (Windows)"
258 : ( $os eq 'macos' ) ? "APFS RAM-Disk on $rm_base (macOS)"
259 : "tmpfs mountpoint on $rm_base (Linux)";
260 }
261 else {
262 $ramdisk_dir = '';
263 $is_mounted = 0;
264 $mount_desc = "Local Storage (No RAM-disk active)";
265 }
266 }
267  
268 # Populate paths and subdirectories
269 my ( $tbl_dir, $schema_dir, $config_dir, $lock_dir, $session_dir, $tbl_rdir, $schema_rdir, $config_rdir, $shmem_dir );
270  
271 if ($is_mounted) {
272 $tbl_dir = $self->path('table_dir') || "$dbase_dir/table";
273 $schema_dir = $self->path('schema_dir') || "$dbase_dir/schema";
274 $config_dir = $self->path('config_dir') || "$dbase_dir/config";
275  
276 $tbl_rdir = $opts{table_rdir} || "$ramdisk_dir/table";
277 $schema_rdir = $opts{schema_rdir} || "$ramdisk_dir/schema";
278 $config_rdir = $opts{config_rdir} || "$ramdisk_dir/config";
279 $lock_dir = "$ramdisk_dir/lock";
280 $session_dir = "$ramdisk_dir/session";
281 $shmem_dir = "$ramdisk_dir/shmem";
282  
283 $self->path(
284 ramdisk_dir => $ramdisk_dir,
285 table_rdir => $tbl_rdir,
286 schema_rdir => $schema_rdir,
287 config_rdir => $config_rdir,
288 lock_dir => $lock_dir,
289 session_dir => $session_dir,
290 shmem_dir => $shmem_dir,
291 );
292  
293 my $old_umask = umask(0000);
294 my $make_ok = eval {
295 for my $dir ( $ramdisk_dir, $tbl_rdir, $schema_rdir, $config_rdir, $lock_dir, $session_dir, $shmem_dir, "$ramdisk_dir/journal" ) {
296 $self->make_path($dir);
297 chmod 0777, $dir if -d $dir;
298 }
299 1;
300 };
301 umask($old_umask);
302 if ( !$make_ok ) {
303 $is_mounted = 0;
304 $ramdisk_dir = '';
305 $mount_desc = "Local Storage (No RAM-disk active)";
306 }
307 }
308  
309 if (!$is_mounted) {
310 # Strict zero-fallback: when unmounted, all *_rdir paths are empty and removed.
311 $tbl_dir = $self->path('table_dir') || "$dbase_dir/table";
312 $schema_dir = $self->path('schema_dir') || "$dbase_dir/schema";
313 $config_dir = $self->path('config_dir') || "$dbase_dir/config";
314 $lock_dir = $self->path('lock_dir') || "$dbase_dir/lock";
315 $session_dir = $self->path('session_dir') || "$dbase_dir/session";
316  
317 $tbl_rdir = '';
318 $schema_rdir = '';
319 $config_rdir = '';
320 $shmem_dir = '';
321  
322 $self->path(
323 ramdisk_dir => '',
324 table_rdir => '',
325 schema_rdir => '',
326 config_rdir => '',
327 lock_dir => $lock_dir,
328 session_dir => $session_dir,
329 );
330 delete $self->{_path}->{shmem_dir};
331 delete $self->{_path}->{ramdisk_dir};
332 delete $self->{_path}->{table_rdir};
333 delete $self->{_path}->{schema_rdir};
334 delete $self->{_path}->{config_rdir};
335 }
336  
337 # Record mount status in cache and config
338 $self->set_cache(
339 'ramdisk', 'mount',
340 {
341 ramdisk_dir => $ramdisk_dir,
342 is_mounted => $is_mounted ? 1 : 0,
343 mount_desc => $mount_desc,
344 sys => $sys,
345 }
346 );
347 if ($is_mounted) {
348 $self->config(
349 ramdisk_dir => $ramdisk_dir,
350 table_rdir => $tbl_rdir,
351 schema_rdir => $schema_rdir,
352 config_rdir => $config_rdir,
353 ramdisk_mounted => 1,
354 );
355 }
356 else {
357 $self->config(
358 ramdisk_dir => '',
359 table_rdir => '',
360 schema_rdir => '',
361 config_rdir => '',
362 ramdisk_mounted => 0,
363 );
364 }
365  
366 my $tbl_res = '';
367 if ( defined $tableid && length $tableid && $is_mounted ) {
368 $tbl_res = $self->ramdisk_ensure($tableid) // '';
369 }
370  
371 $disk_size = $self->config('ramdisk_size') // '512M';
372  
373 $self->set_cache("ramdisk", "is_mounted", $is_mounted);
374
375 return {
376 os => $sys->{os},
377 table => $tbl_res,
378 ramdisk_dir => $is_mounted ? $self->path('ramdisk_dir') : '',
379 table_dir => $tbl_dir,
380 lock_dir => $self->path('lock_dir'),
381 session_dir => $self->path('session_dir'),
382 schema_dir => $schema_dir,
383 config_dir => $config_dir,
384 table_rdir => $tbl_rdir,
385 schema_rdir => $schema_rdir,
386 config_rdir => $config_rdir,
387 shmem_dir => $is_mounted ? ( $self->path('shmem_dir') // '' ) : '',
388 ramdisk_size => $disk_size,
389 is_mounted => $is_mounted,
390 mount_desc => $mount_desc,
391 script_pl => $sys->{script_pl},
392 script_bat => $sys->{script_bat},
393 instructions => $sys->{instructions},
394 };
395 }
396  
397 # my $ramdisk_path = $adb->ramdisk_path($tableid, [$with_ext]);
398 # Symmetric counterpart to table_path($tableid, [$with_ext]).
399 # Resolves root directory and base path for table in ramdisk/table/$tableid.
400 # Supports custom table_dir (e.g. table_dir => 'siparis', table_dir => '').
401 # ------------------------------------------------
402 sub ramdisk_path {
403 my ( $self, $tableid, $with_ext ) = @_;
404  
405 $tableid = $self->sanitize_table($tableid);
406 return "" unless defined $tableid && length $tableid;
407  
408 my $ramdisk_dir = $self->ramdisk_dir or return "";
409 my $table_info = $self->table_info($tableid);
410  
411 my $target_dir;
412 if ( $table_info && exists $table_info->{table_dir} ) {
413 my $tdir = $table_info->{table_dir};
414 if ( defined $tdir && length $tdir ) {
415 $tdir =~ s{^[\\/]+|[\\/]+$}{}g;
416 $target_dir = "$ramdisk_dir/$tdir";
417 }
418 else {
419 $target_dir = $ramdisk_dir;
420 }
421 $self->make_path($target_dir);
422 }
423 else {
424 $target_dir = $self->{_path}->{table_rdir} || $self->path('table_rdir') || "$ramdisk_dir/table";
425 }
426  
427 my $target = "$target_dir/$tableid";
428  
429 return $target . ( $with_ext ? ".$self->{db_ext}" : "" );
430 }
431  
432 # Returns target ramdisk file path (.db for records, .inx for meta/indexes)
433 sub ramdisk_file_for {
434 my ( $self, $tableid, $key, $type ) = @_;
435  
436 $tableid = $self->sanitize_table($tableid);
437 return unless defined $tableid && length $tableid;
438  
439 my $base_path = $self->ramdisk_path($tableid) or return;
440  
441 my $ext;
442 if ( defined $type && $type ne '' ) {
443 $ext = $type;
444 }
445 else {
446 my $table_info = $self->table_info($tableid);
447 my $is_simple = $self->config('use_simple') || ( $table_info && $table_info->{use_simple} );
448  
449 if ( $is_simple || ( defined $key && $key =~ /^\d+$/ ) ) {
450 $ext = $self->{db_ext} // 'db';
451 }
452 else {
453 $ext = 'inx';
454 }
455 }
456  
457 my $target = "${base_path}.${ext}";
458 return $target;
459 }
460  
461 # Checks TTL expiration on ramdisk file.
462 # Strictly evaluated ONLY for Tier 3 (use_ramdisk => 3). Tiers 1 and 2 never expire.
463 # Unlinks expired file and returns 0.
464 sub _check_ramdisk_ttl {
465 my ( $self, $tableid, $file_path ) = @_;
466 return 1 unless -e $file_path;
467  
468 my $table_info = $self->table_info($tableid);
469 my $use_ramdisk = $table_info ? ( $table_info->{use_ramdisk} // 0 ) : 0;
470 return 1 unless $use_ramdisk == 3;
471  
472 my $ttl = $table_info ? ( $table_info->{ramdisk_ttl} // 300 ) : 300;
473 if ( defined $ttl && $ttl > 0 ) {
474 my $mtime = ( stat($file_path) )[9];
475 if ( defined $mtime && ( time() - $mtime ) > $ttl ) {
476 $self->table_close($file_path);
477 unlink $file_path;
478 return 0;
479 }
480 }
481 return 1;
482 }
483  
484 my %RAMDISK_ENSURING;
485  
486 # my $ramdisk_path = $adb->ramdisk_ensure($tableid);
487 # Ensures ramdisk for use_ramdisk => 1 or 2 is populated.
488 # Automatically triggers ramdisk_preload if files are absent.
489 # For Tier 3 (use_ramdisk => 3), checks TTL on RAM-disk .db without physical preloading.
490 # ------------------------------------------------
491 sub ramdisk_ensure {
492 my ( $self, $tableid ) = @_;
493  
494 $tableid or return;
495 return unless $self->ramdisk_is_mounted();
496 return if $RAMDISK_ENSURING{$tableid};
497  
498 my $table_info = $self->table_info($tableid);
499 my $use_ramdisk = $table_info ? ( $table_info->{use_ramdisk} // 0 ) : 0;
500 return unless $use_ramdisk;
501  
502 $RAMDISK_ENSURING{$tableid} = 1;
503  
504 my $ramdisk_path = $self->ramdisk_path($tableid);
505 unless ( $ramdisk_path ) {
506 delete $RAMDISK_ENSURING{$tableid};
507 return;
508 }
509  
510 # For use_ramdisk == 3: volatile pure RAM table.
511 # Zero physical disk files, no preloading from physical disk!
512 if ( $use_ramdisk == 3 ) {
513 my $db_ext = $self->{db_ext} // 'db';
514 my $ram_db = "$ramdisk_path.$db_ext";
515 $self->_check_ramdisk_ttl( $tableid, $ram_db );
516 delete $RAMDISK_ENSURING{$tableid};
517 return $ramdisk_path;
518 }
519  
520 my $table_path = $self->table_path($tableid);
521 my $needs_preload = 0;
522  
523 # For use_ramdisk == 2 or 4: ensure .db is present in RAM-disk
524 # Note: Tiers 1, 2, and 4 do not expire via TTL as they are synchronized with physical disk.
525 if ( $use_ramdisk == 2 || $use_ramdisk == 4 ) {
526 my $db_ext = $self->{db_ext} // 'db';
527 my $src_db = "$table_path.$db_ext";
528 my $ram_db = "$ramdisk_path.$db_ext";
529 if ( -e $src_db && !-e $ram_db ) {
530 $needs_preload = 1;
531 }
532 }
533  
534 # For use_ramdisk >= 1: ensure all secondary & lookup index files are present
535 unless ($needs_preload) {
536 for my $ext ( qw( inx fld src fac unq slg ajw ajn ) ) {
537 my $src_file = "$table_path.$ext";
538 my $ram_file = "$ramdisk_path.$ext";
539 if ( -e $src_file && !-e $ram_file ) {
540 $needs_preload = 1;
541 last;
542 }
543 }
544 }
545  
546 if ($needs_preload) {
547 $self->ramdisk_preload($tableid);
548 }
549  
550 delete $RAMDISK_ENSURING{$tableid};
551 return $ramdisk_path;
552 }
553  
554 # my @data = $adb->ramdisk_read($tableid, $key, [$type]);
555 # Reads entry from ramdisk/$tableid.db (for numeric/records) or ramdisk/$tableid.inx (for meta/keys).
556 # ------------------------------------------------
557 sub ramdisk_read {
558 my ( $self, $tableid, $key, $type ) = @_;
559  
560 $tableid or return;
561 defined $key && $key ne '' or return;
562  
563 my $table_info = $self->table_info($tableid);
564 my $use_ramdisk = $table_info ? ( $table_info->{use_ramdisk} // $table_info->{use_cache} // 0 ) : 0;
565 return unless $use_ramdisk;
566  
567 $self->ramdisk_ensure($tableid);
568  
569 my $ramdisk_file = $self->ramdisk_file_for( $tableid, $key, $type ) or return;
570 return unless -e $ramdisk_file;
571  
572 return unless $self->_check_ramdisk_ttl( $tableid, $ramdisk_file );
573  
574 my $res = $self->recs_get( $ramdisk_file, $key );
575 return unless $res && defined $res->{$key} && $res->{$key} ne '';
576  
577 # Sliding TTL refresh on successful read for Tier 3
578 if ( $use_ramdisk == 3 ) {
579 utime( undef, undef, $ramdisk_file );
580 }
581  
582 return $self->db_decode( $res->{$key} );
583 }
584  
585 # my $ok = $adb->ramdisk_write($tableid, $key, @records);
586 # Writes entry to ramdisk/$tableid.db (for numeric/records) or ramdisk/$tableid.inx (for meta/keys).
587 # ------------------------------------------------
588 sub ramdisk_write {
589 my ( $self, $tableid, $key, @records ) = @_;
590  
591 $tableid or return;
592 return unless $self->ramdisk_is_mounted();
593 defined $key && $key ne '' or return;
594 return unless @records;
595  
596 my $table_info = $self->table_info($tableid);
597 my $use_ramdisk = $table_info ? ( $table_info->{use_ramdisk} // $table_info->{use_cache} // 0 ) : 0;
598 return unless $use_ramdisk;
599  
600 my $ramdisk_file = $self->ramdisk_file_for( $tableid, $key ) or return;
601 my $encoded_val = $self->db_encode(@records);
602  
603 $self->recs_put( $ramdisk_file, [ $key, $encoded_val ] );
604 return 1;
605 }
606  
607 # my $ok = $adb->ramdisk_delete($tableid, [$key], [$type]);
608 # Invalidates entry from ramdisk/$tableid.db / .inx or removes entire table ramdisk files.
609 # ------------------------------------------------
610 sub ramdisk_delete {
611 my ( $self, $tableid, $key, $type ) = @_;
612  
613 $tableid or return;
614 return unless $self->ramdisk_is_mounted();
615  
616 my $table_info = $self->table_info($tableid);
617 my $use_ramdisk = $table_info ? ( $table_info->{use_ramdisk} // $table_info->{use_cache} // 0 ) : 0;
618 return unless $use_ramdisk;
619  
620 if ( defined $key && $key ne '' ) {
621 my $ramdisk_file = $self->ramdisk_file_for( $tableid, $key, $type );
622 if ( $ramdisk_file && -e $ramdisk_file ) {
623 $self->recs_del( $ramdisk_file, $key );
624 }
625 }
626 else {
627 my $ramdisk_path = $self->ramdisk_path($tableid) or return;
628 my $db_ext = $self->{db_ext} // 'db';
629  
630 foreach my $ext ( $db_ext, qw( inx fld src fac unq slg ajw ajn ) ) {
631 my $file = "$ramdisk_path.$ext";
632 if ( -e $file ) {
633 $self->table_close($file);
634 unlink $file;
635 }
636 }
637 }
638  
639 return 1;
640 }
641  
642 # my $ok = $adb->ramdisk_preload($tableid);
643 # Preloads records and metadata from table/ into ramdisk/ based on use_ramdisk (1: indexes, 2: data+indexes).
644 # Uses atomic temporary writes (.tmp.$$) to prevent multi-process race conditions.
645 # ------------------------------------------------
646 sub ramdisk_preload {
647 my ( $self, $tableid ) = @_;
648  
649 $tableid or return;
650 $tableid = $self->sanitize_table($tableid);
651 return unless defined $tableid && length $tableid;
652 return unless $self->ramdisk_is_mounted();
653  
654 my $table_info = $self->table_info($tableid);
655 my $use_ramdisk = $table_info ? ( $table_info->{use_ramdisk} // $table_info->{use_cache} // 0 ) : 0;
656 return unless $use_ramdisk;
657 return if $use_ramdisk == 3;
658  
659 my $tbl_dir = $self->{_path}->{table_rdir} || $self->path('table_rdir') or return;
660 unless ( -d $tbl_dir ) {
661 warn "[AMBERDB_RAMDISK] RAM-disk tables directory does not exist: $tbl_dir\n";
662 return;
663 }
664  
665 my $table_path = $self->table_path($tableid);
666 my $ramdisk_path = $self->ramdisk_path($tableid);
667 my $db_ext = $self->{db_ext} // 'db';
668  
669 my $_copy_atomic = sub {
670 my ( $src_file, $dst_file ) = @_;
671 return unless -e $src_file;
672  
673 require File::Copy;
674 my $tmp_dst = "$dst_file.tmp.$$";
675 unlink $tmp_dst if -e $tmp_dst;
676  
677 $self->table_close($src_file) if $self->{_db}->{$src_file};
678  
679 if ( File::Copy::copy( $src_file, $tmp_dst ) ) {
680 $self->table_close($dst_file) if -e $dst_file && $self->{_db}->{$dst_file};
681 unlink $dst_file if -e $dst_file;
682 rename $tmp_dst, $dst_file;
683 }
684 };
685  
686 # 1. Preload data file .db only for use_ramdisk == 2 or 4
687 if ( $use_ramdisk == 2 || $use_ramdisk == 4 ) {
688 my $src_db = "$table_path.$db_ext";
689 my $dst_db = "$ramdisk_path.$db_ext";
690 $_copy_atomic->( $src_db, $dst_db );
691 }
692  
693 # 2. Preload index & lookup files (.inx, .fld, .src, .fac, .unq, .slg) for use_ramdisk >= 1 and != 3
694 if ( $use_ramdisk >= 1 && $use_ramdisk != 3 ) {
695 foreach my $ext ( qw( inx fld src fac unq slg ajw ajn ) ) {
696 my $src_file = "$table_path.$ext";
697 my $dst_file = "$ramdisk_path.$ext";
698 $_copy_atomic->( $src_file, $dst_file );
699 }
700 }
701  
702 return 1;
703 }
704  
705 # ============================================================================
706 # Tier 4 (Async Write-Behind) Sync Event Tracking & Background Daemon Engine
707 # ============================================================================
708  
709 # Returns absolute path to the sync events journal slot.
710 # ------------------------------------------------
711 sub ramdisk_sync_db_path {
712 my ($self) = @_;
713 return $self->journal_slot("sync_ramdisk");
714 }
715  
716 # Marks a record dirty in the RAM-disk sync events journal.
717 # Formats entry as: [ 'recs', $tableid, $file_path, $rid, $action, $pos, $raw, time() ]
718 # Appends to $journal_dir/sync_ramdisk
719 # ------------------------------------------------
720 sub ramdisk_mark_dirty {
721 my ( $self, $file_path, $rid, $action, $raw, $pos ) = @_;
722  
723 return unless defined $file_path && length $file_path;
724 return unless defined $rid && length $rid;
725 $action //= 'edit';
726  
727 return unless $self->ramdisk_is_mounted();
728  
729 my $db_ext = $self->{db_ext} // 'db';
730 my ($fname) = $file_path =~ m{([^/\\:]+)$};
731 $fname =~ s{\.\Q$db_ext\E$}{} if defined $fname;
732 my $tableid = $fname // 'default';
733  
734 my $norm_action = ( $action eq '1' || $action eq 'add' || $action eq 'insert' ) ? 'add'
735 : ( $action eq '2' || $action eq 'edit' || $action eq 'modify' || $action eq 'update' ) ? 'edit'
736 : ( $action eq '3' || $action eq 'del' || $action eq 'delete' ) ? 'del'
737 : $action;
738  
739 # If raw payload not supplied and not a delete, fetch from RAM-disk
740 if ( !defined $raw && $norm_action ne 'del' ) {
741 my $ram_path = $tableid ? $self->ramdisk_path($tableid) : undef;
742 my $ram_file = $ram_path ? "$ram_path.$db_ext" : undef;
743 if ( $ram_file && -e $ram_file ) {
744 my $rec_hash = $self->recs_get( $ram_file, $rid );
745 $raw = $rec_hash ? $rec_hash->{$rid} : undef;
746 }
747 }
748  
749 $self->journal_append( 'sync_ramdisk', [ 'recs', $tableid, $file_path, $rid, $norm_action, $pos // '', $raw, time() ] );
750 return 1;
751 }
752  
753 # Removes dirty tracking marker for given record (used on immediate dual-write / txn commit).
754 # In the journal write-behind architecture, transactional writes bypass ramdisk_mark_dirty
755 # entirely via immediate dual-write. Retained as a harmless compatibility helper.
756 # ------------------------------------------------
757 sub ramdisk_unmark_dirty {
758 my ( $self, $file_path, $rid ) = @_;
759 return 1;
760 }
761  
762 # Synchronizes pending dirty events from journal (sync_ramdisk) to persistent disk.
763 # If $target_table is specified, syncs only events matching that table.
764 # Atomically rotates active journal file: sync_ramdisk -> sync_ramdisk_${epoch}
765 # Processes all pending rotated journals, applies coalescing, and removes processed files.
766 # Returns number of synced events.
767 # ------------------------------------------------
768 sub ramdisk_sync {
769 my ( $self, $target_table ) = @_;
770  
771 return 0 unless $self->ramdisk_is_mounted();
772  
773 # 1. Rotate active sync_ramdisk journal under lock
774 $self->journal_rotate('sync_ramdisk');
775  
776 # 2. Scan for rotated journal files
777 my @journal_files = $self->journal_scan('sync_ramdisk_');
778 return 0 unless @journal_files;
779  
780 my $db_ext = $self->{db_ext} // 'db';
781 my $synced_count = 0;
782  
783 foreach my $jfile (@journal_files) {
784 my @entries = $self->journal_read($jfile);
785 next unless @entries;
786  
787 my ( @to_process, @to_keep );
788 if ( defined $target_table && length $target_table ) {
789 for my $e (@entries) {
790 if ( ( $e->{tableid} // '' ) eq $target_table ) {
791 push @to_process, $e;
792 }
793 else {
794 push @to_keep, $e;
795 }
796 }
797 }
798 else {
799 @to_process = @entries;
800 }
801  
802 # If partial sync with target_table, re-queue events for other tables
803 if (@to_keep) {
804 my @re_entries = map {
805 [ $_->{type}, $_->{tableid}, $_->{file_path}, $_->{key}, $_->{action}, $_->{pos}, $_->{payload}, $_->{epoch} ]
806 } @to_keep;
807 $self->journal_append( 'sync_ramdisk', @re_entries );
808 }
809  
810 # 3. In-batch state machine coalescing
811 # (add + edit) => add
812 # (add + del) => canceled (never touches persistent disk)
813 # (edit + edit)=> edit
814 # (edit + del) => del
815 # (del + add) => edit
816 my %coalesced;
817 my @ordered_keys;
818  
819 foreach my $entry (@to_process) {
820 my $file_path = $entry->{file_path};
821 my $rid = $entry->{key};
822 my $composite = "$file_path\0$rid";
823 my $action = $entry->{action};
824  
825 if ( !exists $coalesced{$composite} ) {
826 push @ordered_keys, $composite;
827 $coalesced{$composite} = {
828 entry => $entry,
829 action => $action,
830 raw => $entry->{payload},
831 };
832 }
833 else {
834 my $state = $coalesced{$composite};
835 my $old_action = $state->{action};
836  
837 if ( $old_action eq 'add' || $old_action eq '1' ) {
838 if ( $action eq 'edit' || $action eq '2' ) {
839 $state->{action} = 'add';
840 $state->{raw} = $entry->{payload} if defined $entry->{payload};
841 $state->{entry} = $entry;
842 }
843 elsif ( $action eq 'del' || $action eq '3' ) {
844 delete $coalesced{$composite};
845 @ordered_keys = grep { $_ ne $composite } @ordered_keys;
846 }
847 }
848 elsif ( $old_action eq 'edit' || $old_action eq '2' ) {
849 if ( $action eq 'edit' || $action eq '2' ) {
850 $state->{action} = 'edit';
851 $state->{raw} = $entry->{payload} if defined $entry->{payload};
852 $state->{entry} = $entry;
853 }
854 elsif ( $action eq 'del' || $action eq '3' ) {
855 $state->{action} = 'del';
856 $state->{raw} = undef;
857 $state->{entry} = $entry;
858 }
859 }
860 elsif ( $old_action eq 'del' || $old_action eq '3' ) {
861 if ( $action eq 'add' || $action eq '1' ) {
862 $state->{action} = 'edit';
863 $state->{raw} = $entry->{payload} if defined $entry->{payload};
864 $state->{entry} = $entry;
865 }
866 }
867 }
868 }
869  
870 # 4. Flush coalesced events to persistent disk
871 foreach my $composite (@ordered_keys) {
872 my $state = $coalesced{$composite};
873 next unless $state;
874  
875 my $entry = $state->{entry};
876 my $action = $state->{action};
877 my $raw = $state->{raw};
878 my $file_path = $entry->{file_path};
879 my $rid = $entry->{key};
880 my $tableid = $entry->{tableid};
881 my $table_info = $self->table_info($tableid);
882 my $table_path = $self->table_path($tableid);
883 my $ramdisk_path = $self->ramdisk_path($tableid);
884  
885 # If raw not present in journal payload, fetch from RAM-disk
886 if ( !defined $raw && ( $action eq 'add' || $action eq 'edit' || $action eq '1' || $action eq '2' ) ) {
887 my $ram_file = "$ramdisk_path.$db_ext";
888 my $rec_hash = -e $ram_file ? $self->recs_get( $ram_file, $rid ) : undef;
889 $raw = $rec_hash ? $rec_hash->{$rid} : undef;
890 }
891  
892 if ( $action eq 'add' || $action eq 'edit' || $action eq '1' || $action eq '2' ) {
893 if ( defined $raw ) {
894 # 1. Sync to persistent disk .db
895 if ( $self->table_write($file_path) ) {
896 $self->recs_put( $file_path, [ $rid, $raw ] );
897 $self->table_close($file_path);
898 }
899  
900 # 2. Sync secondary index files on persistent disk
901 unless ( $self->config('use_simple') || ( $table_info && $table_info->{use_simple} ) ) {
902 my @decoded = ( $rid, $self->db_decode($raw) );
903 my @batch = ( \@decoded );
904  
905 # Base stream indexes
906 $self->records_add( $table_path, $table_info, $tableid, [$rid] );
907 $self->search_add( $table_path, $table_info, $tableid, \@batch );
908 $self->match_add( $table_path, $table_info, \@batch );
909 $self->sort_add( $table_path, $table_info, \@batch );
910 $self->unique_add( $table_path, $table_info, \@batch );
911 $self->slug_add( $table_path, $table_info, $tableid, \@batch ) if $table_info->{slug_block};
912  
913 if ( $table_info->{use_junk} ) {
914 if ( $action eq 'add' || $action eq '1' ) {
915 my $is_junk = $self->junk_rules( $table_info, @decoded );
916 my $tier = $is_junk ? 'B' : 'A';
917 $self->records_add( $table_path, $table_info, $tableid, [$rid], $tier );
918 $self->search_add( $table_path, $table_info, $tableid, \@batch, $tier );
919 $self->match_add( $table_path, $table_info, \@batch, $tier );
920 $self->sort_add( $table_path, $table_info, \@batch, $tier ) if $table_info->{sort_block};
921 $self->facet_add( $table_path, $table_info, \@batch ) if !$is_junk && $table_info->{use_facet};
922 }
923 else {
924 my @mod_pairs = ( [ $rid, [$rid], \@decoded ] );
925 $self->junk_transition( $table_path, $table_info, $tableid, \@mod_pairs );
926 }
927 }
928 else {
929 if ( $action eq 'add' || $action eq '1' ) {
930 $self->facet_add( $table_path, $table_info, \@batch ) if $table_info->{use_facet};
931 }
932 else {
933 my @mod_pairs = ( [ $rid, [$rid], \@decoded ] );
934 $self->facet_modify( $table_path, $table_info, \@mod_pairs ) if $table_info->{use_facet};
935 }
936 }
937 }
938 }
939 }
940 elsif ( $action eq 'del' || $action eq '3' ) {
941 # 1. Delete from persistent disk .db
942 if ( -e $file_path && $self->table_write($file_path) ) {
943 $self->recs_del( $file_path, $rid );
944 $self->table_close($file_path);
945 }
946  
947 # 2. Delete from secondary indexes on persistent disk
948 unless ( $self->config('use_simple') || ( $table_info && $table_info->{use_simple} ) ) {
949 $self->records_del( $table_path, $table_info, [$rid], $tableid );
950 $self->search_del( $table_path, $table_info, $tableid, [ [$rid] ] );
951 $self->match_del( $table_path, $table_info, [ [$rid] ] );
952 $self->sort_del( $table_path, $table_info, [ [$rid] ] ) if $table_info->{sort_block};
953 $self->unique_del( $table_path, $table_info, [ [$rid] ] );
954 $self->slug_del( $table_path, $table_info, $tableid, [ [$rid] ] ) if $table_info->{slug_block};
955  
956 if ( $table_info->{use_junk} ) {
957 $self->records_del( $table_path, $table_info, [$rid], $tableid, ['A', 'B'] );
958 $self->search_del( $table_path, $table_info, $tableid, [ [$rid] ], ['A', 'B'] );
959 $self->match_del( $table_path, $table_info, [ [$rid] ], ['A', 'B'] );
960 $self->sort_del( $table_path, $table_info, [ [$rid] ], ['A', 'B'] ) if $table_info->{sort_block};
961 $self->facet_del( $table_path, $table_info, [ [$rid] ] ) if $table_info->{use_facet};
962 }
963 else {
964 $self->facet_del( $table_path, $table_info, [ [$rid] ] ) if $table_info->{use_facet};
965 }
966 }
967 }
968  
969 $synced_count++;
970 }
971  
972 # 5. Clean up processed rotated journal file and its lock
973 $self->journal_delete($jfile);
974 }
975  
976 return $synced_count;
977 }
978  
979 # Flushes all pending dirty events across all tables to persistent disk.
980 # ------------------------------------------------
981 sub ramdisk_sync_all {
982 my ($self) = @_;
983 return $self->ramdisk_sync();
984 }
985  
986 # ============================================================================
987 # Shared Memory (shmem) Operations - Pure RAM-Disk Key-Value Store
988 # Strictly active only when RAM-disk is mounted (zero fallback to disk)
989 # ============================================================================
990  
991 sub set_shmem {
992 my ( $self, $key, $val, $ttl ) = @_;
993 return unless defined $key && length $key;
994 return unless $self->ramdisk_is_mounted();
995  
996 my $shm_dir = $self->path('shmem_dir');
997 return unless defined $shm_dir && -d $shm_dir;
998  
999 $key =~ s{[^a-zA-Z0-9_.-]}{_}g;
1000 my $file = "$shm_dir/$key.shm";
1001  
1002 my $payload = {
1003 expire => ( defined $ttl && $ttl > 0 ) ? ( time + $ttl ) : 0,
1004 data => $val,
1005 };
1006  
1007 my $raw = $self->db_encode($payload);
1008 return unless defined $raw;
1009  
1010 my $old_umask = umask(0000);
1011 if ( open my $fh, '>:raw', $file ) {
1012 flock( $fh, 2 ); # LOCK_EX
1013 print $fh $raw;
1014 close $fh;
1015 chmod 0666, $file;
1016 }
1017 umask($old_umask);
1018 return 1;
1019 }
1020  
1021 sub get_shmem {
1022 my ( $self, $key ) = @_;
1023 return unless defined $key && length $key;
1024 return unless $self->ramdisk_is_mounted();
1025  
1026 my $shm_dir = $self->path('shmem_dir');
1027 return unless defined $shm_dir && -d $shm_dir;
1028  
1029 $key =~ s{[^a-zA-Z0-9_.-]}{_}g;
1030 my $file = "$shm_dir/$key.shm";
1031 return unless -e $file;
1032  
1033 my $raw;
1034 if ( open my $fh, '<:raw', $file ) {
1035 flock( $fh, 1 ); # LOCK_SH
1036 local $/;
1037 $raw = <$fh>;
1038 close $fh;
1039 }
1040 return unless defined $raw && length $raw;
1041  
1042 my $payload = $self->db_decode($raw);
1043 return unless ref($payload) eq 'HASH';
1044  
1045 if ( $payload->{expire} && $payload->{expire} < time ) {
1046 unlink $file;
1047 return;
1048 }
1049  
1050 return $payload->{data};
1051 }
1052  
1053 sub del_shmem {
1054 my ( $self, $key ) = @_;
1055 return 0 unless defined $key && length $key;
1056 return 0 unless $self->ramdisk_is_mounted();
1057  
1058 my $shm_dir = $self->path('shmem_dir');
1059 return 0 unless defined $shm_dir && -d $shm_dir;
1060  
1061 $key =~ s{[^a-zA-Z0-9_.-]}{_}g;
1062 my $file = "$shm_dir/$key.shm";
1063 return unlink $file if -e $file;
1064 return 0;
1065 }
1066  
1067 1;
1068  
1069 __END__