volatile_map 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1a675867ad0e08a4b1766a57ce25d811c838e61eb7fae00deac361d4ab201ffa
+  data.tar.gz: 9cdb03fb55c6cdd4c55878334262fb44be1cb5ccfa8d70073728774034ac235a
+SHA512:
+  metadata.gz: 014fb93aee4fd8cf86a78c2e514f4fd5f40c9d389d9a84393c3b4ec62cf9b81411a628b0356f9b2211bf7d275683994229a97cbeb9847e80343e519aa95d8c54
+  data.tar.gz: aee837e05d68f3e6aab4fa7e0f2fe7b46f64bbea6e64f588e7f887fc84f555545d23258fce0d8e22a3b5e26a16bc99635eded24790ba9a0e29745d99e6fdf71b

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"volatile_map" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["mehmetemininac@gmail.com"](mailto:"mehmetemininac@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Mehmet Emin INAC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,81 @@
+# VolatileMap
+
+`VolatileMap` is a Ruby C extension that provides a `Hash`-like container whose
+entries automatically expire. Each instance has a TTL (time-to-live, in
+seconds); entries older than the TTL are evicted on the next garbage-collection
+cycle, and also lazily on read access. Reading or writing an entry refreshes
+its timestamp, so frequently-touched keys stay alive.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "volatile_map"
+```
+
+Or install directly:
+
+```bash
+gem install volatile_map
+```
+
+## Usage
+
+```ruby
+require "volatile_map"
+
+# TTL is in seconds (Float or Integer)
+cache = VolatileMap.new(0.5)
+
+cache["session"] = { user_id: 42 }
+cache["session"]            # => { user_id: 42 }
+cache.key?("session")       # => true
+cache.size                  # => 1
+
+sleep 1
+GC.start                    # sweep happens just after GC
+
+cache.size                  # => 0
+cache["session"]            # => nil
+```
+
+### API
+
+- `VolatileMap.new(ttl)` — construct a map with the given TTL in seconds.
+- `map[key] = value` — store a value; resets the entry's timestamp.
+- `map[key]` — retrieve a value; returns `nil` if missing or expired.
+  Refreshes the timestamp on a hit.
+- `map.delete(key)` — remove a key; returns the prior value or `nil`.
+- `map.key?(key)` — `true` if the key exists and has not expired.
+  Also evicts and refreshes like `[]`.
+- `map.size` — number of entries currently stored.
+- `map.ttl` — the configured TTL in seconds.
+
+### Semantics
+
+- TTL is measured against a monotonic clock (`CLOCK_MONOTONIC`), so wall-clock
+  jumps do not affect expiry.
+- Eviction happens at two points:
+  1. After every GC cycle (via a postponed job that scans the internal hash).
+  2. Lazily on read (`[]`, `key?`) so entries cannot outlive their TTL even if
+     no GC has run since they expired.
+- Writes (`[]=`) and successful reads (`[]`, `key?` returning true) refresh the
+  entry's timestamp.
+
+### Caveats
+
+- The map strongly retains its keys and values until they expire. It is not a
+  weak-reference container.
+- Not Ractor-shareable in this release.
+- Not thread-safe; wrap with your own mutex if you mutate from multiple threads.
+
+## Development
+
+Run `bin/setup` to install dependencies, then `rake compile` to build the
+extension and `rake spec` to run the tests.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rake/extensiontask"
+
+ENV["VOLATILE_MAP_TEST_HELPERS"] = "1" unless ENV["NO_TEST_ENV"]
+
+RSpec::Core::RakeTask.new(:spec)
+
+Rake::ExtensionTask.new "volatile_map" do |ext|
+  ext.lib_dir = "lib"
+  ext.ext_dir = 'ext/volatile_map'
+end
+
+task default: [:compile, :spec]

data/ext/volatile_map/extconf.rb

@@ -0,0 +1,11 @@
+require "mkmf"
+
+$srcs = Dir.glob("#{__dir__}/**/*.c")
+
+have_func("rb_postponed_job_preregister", "ruby.h")
+
+if ENV["VOLATILE_MAP_TEST_HELPERS"] == "1"
+  $defs << "-DVOLATILE_MAP_TEST_HELPERS"
+end
+
+create_makefile("volatile_map")

data/ext/volatile_map/test_helpers.c

@@ -0,0 +1,20 @@
+#include "test_helpers.h"
+
+static double test_time;
+
+int test_clock_gettime(clockid_t _clk_id, struct timespec *tp) {
+  tp->tv_sec = (int)test_time;
+  tp->tv_nsec = 0;
+
+  return 0;
+}
+
+VALUE vm_set_time(VALUE _klass, VALUE time) {
+  test_time = NUM2DBL(time);
+
+  return time;
+}
+
+void init_test_helpers(VALUE klass) {
+  rb_define_singleton_method(klass, "set_test_clock!", vm_set_time, 1);
+}

data/ext/volatile_map/test_helpers.h

@@ -0,0 +1,7 @@
+#include <ruby.h>
+#include <time.h>
+
+int test_clock_gettime(clockid_t, struct timespec *);
+void init_test_helpers(VALUE klass);
+
+#define clock_gettime test_clock_gettime

data/ext/volatile_map/volatile_map.c

@@ -0,0 +1,252 @@
+#include <time.h>
+#include "volatile_map.h"
+
+#ifdef VOLATILE_MAP_TEST_HELPERS
+#include "test_helpers.h"
+#endif
+
+#ifndef MAX
+#define MAX(a, b) ((a) > (b) ? (a) : (b))
+#endif
+
+static VolatileMap **vm_dirty_array = NULL;
+static size_t vm_dirty_len = 0;
+static size_t vm_dirty_capacity = 0;
+static size_t vm_live_count = 0;
+
+#ifdef HAVE_RB_POSTPONED_JOB_PREREGISTER
+static rb_postponed_job_handle_t vm_drain_job_handle;
+#endif
+
+struct vm_drain_ctx {
+  double now;
+  double ttl;
+};
+
+static double now_seconds(void) {
+  struct timespec ts;
+  clock_gettime(CLOCK_MONOTONIC, &ts);
+
+  return (double)ts.tv_sec + (double)ts.tv_nsec / 1e9;
+}
+
+static bool is_stale(double ttl, VALUE entry, double now) {
+  double ts = NUM2DBL(RARRAY_AREF(entry, 1));
+
+  return (now - ts) > ttl;
+}
+
+static int drain_entry(VALUE _key, VALUE entry, VALUE arg) {
+  struct vm_drain_ctx *ctx = (struct vm_drain_ctx *)arg;
+
+  if(!RB_TYPE_P(entry, T_ARRAY) || RARRAY_LEN(entry) < 2) return ST_CONTINUE;
+
+  if(is_stale(ctx->ttl, entry, ctx->now)) return ST_DELETE;
+
+  return ST_CONTINUE;
+}
+
+static void vm_drain_dirty(void *_ptr) {
+  double now = now_seconds();
+
+  for(size_t i = 0; i < vm_dirty_len; i++) {
+    VolatileMap *vm = vm_dirty_array[i];
+
+    if(RHASH_SIZE(vm->storage) == 0) continue;
+
+    struct vm_drain_ctx ctx = { now, vm->ttl };
+
+    rb_hash_foreach(vm->storage, drain_entry, (VALUE)&ctx);
+  }
+
+  vm_dirty_len = 0;
+}
+
+static inline void schedule_draining(void) {
+  #ifdef HAVE_RB_POSTPONED_JOB_PREREGISTER
+    rb_postponed_job_trigger(vm_drain_job_handle);
+  #else
+    rb_postponed_job_register_one(0, vm_drain_dirty, NULL);
+  #endif
+}
+
+static void rb_mark_volatile_map(void *ptr) {
+  VolatileMap *vm = (VolatileMap *)ptr;
+
+  rb_gc_mark_movable(vm->storage);
+
+  if(RHASH_SIZE(vm->storage) > 0 && vm_dirty_len < vm_dirty_capacity) {
+    vm_dirty_array[vm_dirty_len++] = vm;
+
+    schedule_draining();
+  }
+}
+
+static void rb_free_volatile_map(void *ptr) {
+  VolatileMap *vm = (VolatileMap *)ptr;
+
+  xfree(vm);
+
+  if(vm_live_count > 0) vm_live_count--;
+}
+
+static void rb_compact_volatile_map(void *ptr) {
+  VolatileMap *vm = (VolatileMap *)ptr;
+
+  vm->storage = rb_gc_location(vm->storage);
+}
+
+static size_t rb_size_volatile_map(const void *ptr) {
+  VolatileMap *vm = (VolatileMap *)ptr;
+
+  return sizeof(VolatileMap) + rb_funcall(vm->storage, rb_intern("size"), 0);
+}
+
+const rb_data_type_t volatile_map_type = {
+  "VolatileMap",
+  {
+    rb_mark_volatile_map,
+    rb_free_volatile_map,
+    rb_size_volatile_map,
+    rb_compact_volatile_map
+  },
+  0,
+  0,
+  RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+static void ensure_dirty_capacity(void) {
+  if(vm_dirty_capacity >= vm_live_count) return;
+
+  size_t new_cap = MAX((size_t)8, vm_live_count * 2);
+
+  vm_dirty_array = (VolatileMap **)xrealloc(vm_dirty_array, new_cap * sizeof(VolatileMap *));
+  vm_dirty_capacity = new_cap;
+}
+
+VALUE alloc_volatile_map(VALUE klass) {
+  VolatileMap *vm;
+  VALUE obj = TypedData_Make_Struct(klass, VolatileMap, &volatile_map_type, vm);
+
+  vm->storage = rb_hash_new();
+  vm->ttl = 0.0;
+  vm_live_count++;
+
+  ensure_dirty_capacity();
+
+  return obj;
+}
+
+static VolatileMap *vm_get(VALUE self) {
+  VolatileMap *vm;
+  TypedData_Get_Struct(self, VolatileMap, &volatile_map_type, vm);
+
+  return vm;
+}
+
+static VALUE vm_initialize(VALUE self, VALUE ttl) {
+  VolatileMap *vm = vm_get(self);
+  double ttl_value = NUM2DBL(ttl);
+
+  if(ttl_value <= 0.0) rb_raise(rb_eArgError, "TTL must be positive");
+
+  vm->ttl = ttl_value;
+
+  return self;
+}
+
+static VALUE vm_ttl(VALUE self) {
+  return DBL2NUM(vm_get(self)->ttl);
+}
+
+static VALUE vm_aset(VALUE self, VALUE key, VALUE value) {
+  VolatileMap *vm = vm_get(self);
+  VALUE entry = rb_ary_new_from_args(2, value, DBL2NUM(now_seconds()));
+
+  rb_hash_aset(vm->storage, key, entry);
+
+  return value;
+}
+
+static VALUE vm_aref(VALUE self, VALUE key) {
+  VolatileMap *vm = vm_get(self);
+  VALUE entry = rb_hash_lookup2(vm->storage, key, Qundef);
+
+  if(entry == Qundef) return Qnil;
+
+  double now = now_seconds();
+
+  if(is_stale(vm->ttl, entry, now)) {
+    rb_hash_delete(vm->storage, key);
+
+    return Qnil;
+  }
+
+  rb_ary_store(entry, 1, DBL2NUM(now));
+
+  return RARRAY_AREF(entry, 0);
+}
+
+static VALUE vm_delete(VALUE self, VALUE key) {
+  VolatileMap *vm = vm_get(self);
+  VALUE entry = rb_hash_delete(vm->storage, key);
+
+  if(NIL_P(entry) || !RB_TYPE_P(entry, T_ARRAY) || RARRAY_LEN(entry) < 1) return Qnil;
+
+  return RARRAY_AREF(entry, 0);
+}
+
+static VALUE vm_size(VALUE self) {
+  VolatileMap *vm = vm_get(self);
+
+  if(NIL_P(vm->storage)) return INT2FIX(0);
+
+  return ULONG2NUM(RHASH_SIZE(vm->storage));
+}
+
+static VALUE vm_key(VALUE self, VALUE key) {
+  VolatileMap *vm = vm_get(self);
+  VALUE entry = rb_hash_lookup2(vm->storage, key, Qundef);
+
+  if(entry == Qundef) return Qfalse;
+
+  double now = now_seconds();
+
+  if(is_stale(vm->ttl, entry, now)) {
+    rb_hash_delete(vm->storage, key);
+
+    return Qfalse;
+  }
+
+  rb_ary_store(entry, 1, DBL2NUM(now));
+
+  return Qtrue;
+}
+
+void Init_volatile_map(void) {
+  rb_require("volatile_map/version");
+
+  VALUE volatile_map_class = rb_define_class("VolatileMap", rb_cObject);
+
+  rb_define_alloc_func(volatile_map_class, alloc_volatile_map);
+
+  rb_define_method(volatile_map_class, "initialize", vm_initialize, 1);
+  rb_define_method(volatile_map_class, "ttl", vm_ttl, 0);
+  rb_define_method(volatile_map_class, "[]=", vm_aset, 2);
+  rb_define_method(volatile_map_class, "[]", vm_aref, 1);
+  rb_define_method(volatile_map_class, "delete", vm_delete, 1);
+  rb_define_method(volatile_map_class, "size", vm_size, 0);
+  rb_define_method(volatile_map_class, "length", vm_size, 0);
+  rb_define_method(volatile_map_class, "key?", vm_key, 1);
+  rb_define_method(volatile_map_class, "has_key?", vm_key, 1);
+  rb_define_method(volatile_map_class, "include?", vm_key, 1);
+  rb_define_method(volatile_map_class, "member?", vm_key, 1);
+
+#ifdef VOLATILE_MAP_TEST_HELPERS
+  init_test_helpers(volatile_map_class);
+#endif
+
+#ifdef HAVE_RB_POSTPONED_JOB_PREREGISTER
+  vm_drain_job_handle = rb_postponed_job_preregister(0, vm_drain_dirty, NULL);
+#endif
+}

data/ext/volatile_map/volatile_map.h

@@ -0,0 +1,15 @@
+#ifndef VOLATILE_MAP_H
+#define VOLATILE_MAP_H
+
+#include <ruby.h>
+#include <ruby/debug.h>
+
+typedef struct volatile_map_struct {
+  VALUE storage;
+  double ttl;
+} VolatileMap;
+
+VALUE alloc_volatile_map(VALUE klass);
+void Init_volatile_map(void);
+
+#endif

data/lib/volatile_map/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class VolatileMap
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: volatile_map
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mehmet Emin INAC
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: This gem implement a volatile Hash like object which expires its keys
+  based on given TTL.
+email:
+- mehmetemininac@gmail.com
+executables: []
+extensions:
+- ext/volatile_map/extconf.rb
+extra_rdoc_files: []
+files:
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- ext/volatile_map/extconf.rb
+- ext/volatile_map/test_helpers.c
+- ext/volatile_map/test_helpers.h
+- ext/volatile_map/volatile_map.c
+- ext/volatile_map/volatile_map.h
+- lib/volatile_map/version.rb
+homepage: https://github.com/meinac/volatile_map
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/meinac/volatile_map
+  source_code_uri: https://github.com/meinac/volatile_map
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Implements a volatile Hash like object.
+test_files: []