Add atomic load/store.

Author: samuel-williams-shopify

ext/io/buffer/atomic.c

@@ -24,6 +24,23 @@
 	#error "Atomic operations not available on this platform"
 #endif
 
+// Byte swap functions (for endianness conversion)
+static inline uint16_t swap16(uint16_t x) {
+	return ((x & 0xFF00) >> 8) | ((x & 0x00FF) << 8);
+}
+
+static inline uint32_t swap32(uint32_t x) {
+	return ((x & 0xFF000000) >> 24) | ((x & 0x00FF0000) >> 8) |
+	       ((x & 0x0000FF00) << 8) | ((x & 0x000000FF) << 24);
+}
+
+static inline uint64_t swap64(uint64_t x) {
+	return ((x & 0xFF00000000000000ULL) >> 56) | ((x & 0x00FF000000000000ULL) >> 40) |
+	       ((x & 0x0000FF0000000000ULL) >> 24) | ((x & 0x000000FF00000000ULL) >> 8) |
+	       ((x & 0x00000000FF000000ULL) << 8) | ((x & 0x0000000000FF0000ULL) << 24) |
+	       ((x & 0x000000000000FF00ULL) << 40) | ((x & 0x00000000000000FFULL) << 56);
+}
+
 // Helper to get buffer pointer and validate
 static void* get_buffer_pointer(VALUE buffer, size_t offset, size_t size) {
 	void *base;
@@ -81,6 +98,40 @@ static ID RB_IO_BUFFER_DATA_TYPE_S64;
 		return val2num(result); \
 	}
 
+// Helper macro for swap function selection based on size
+#define SWAP_BY_SIZE(size_val, value) \
+	((size_val) == 8 ? (uint8_t)(value) : \
+	 (size_val) == 16 ? swap16((uint16_t)(value)) : \
+	 (size_val) == 32 ? swap32((uint32_t)(value)) : \
+	 swap64((uint64_t)(value)))
+
+// Macro for atomic load (with endianness conversion)
+#define ATOMIC_LOAD_IMPL(name, ctype, atomic_type, size_bits, num2val, val2num, endian, swap_func) \
+	static VALUE atomic_load_##name(VALUE self, size_t offset) { \
+		void *pointer = get_buffer_pointer(self, offset, size_bits / 8); \
+		ctype result = atomic_load((atomic_type*)pointer); \
+		if (endian != RB_IO_BUFFER_HOST_ENDIAN && size_bits > 8) { \
+			if (size_bits == 16) result = (ctype)swap16((uint16_t)result); \
+			else if (size_bits == 32) result = (ctype)swap32((uint32_t)result); \
+			else if (size_bits == 64) result = (ctype)swap64((uint64_t)result); \
+		} \
+		return val2num(result); \
+	}
+
+// Macro for atomic store (with endianness conversion)
+#define ATOMIC_STORE_IMPL(name, ctype, atomic_type, size_bits, num2val, val2num, endian, swap_func) \
+	static VALUE atomic_store_##name(VALUE self, size_t offset, VALUE value) { \
+		void *pointer = get_buffer_pointer(self, offset, size_bits / 8); \
+		ctype converted_value = (ctype)num2val(value); \
+		if (endian != RB_IO_BUFFER_HOST_ENDIAN && size_bits > 8) { \
+			if (size_bits == 16) converted_value = (ctype)swap16((uint16_t)converted_value); \
+			else if (size_bits == 32) converted_value = (ctype)swap32((uint32_t)converted_value); \
+			else if (size_bits == 64) converted_value = (ctype)swap64((uint64_t)converted_value); \
+		} \
+		atomic_store((atomic_type*)pointer, converted_value); \
+		return self; \
+	}
+
 // Macro for atomic compare and swap
 #define ATOMIC_CAS_IMPL(name, ctype, atomic_type, size, num2val, val2num) \
 	static int atomic_cas_##name(VALUE self, size_t offset, VALUE expected_value, VALUE desired_value) { \
@@ -128,6 +179,46 @@ ATOMIC_BITWISE_IMPL(i32, int32_t, atomic_int_least32_t, 4, NUM2INT, INT2NUM, xor
 ATOMIC_BITWISE_IMPL(u64, uint64_t, atomic_uint_least64_t, 8, NUM2ULL, ULL2NUM, xor)
 ATOMIC_BITWISE_IMPL(i64, int64_t, atomic_int_least64_t, 8, NUM2LL, LL2NUM, xor)
 
+// 8-bit types: no swap needed (single byte), Ruby only defines U8/S8 (big-endian)
+ATOMIC_LOAD_IMPL(U8, uint8_t, atomic_uint_least8_t, 8, NUM2UINT, UINT2NUM, RB_IO_BUFFER_BIG_ENDIAN, NULL)
+ATOMIC_LOAD_IMPL(S8, int8_t, atomic_int_least8_t, 8, NUM2INT, INT2NUM, RB_IO_BUFFER_BIG_ENDIAN, NULL)
+
+// 16-bit types
+ATOMIC_LOAD_IMPL(u16, uint16_t, atomic_uint_least16_t, 16, NUM2UINT, UINT2NUM, RB_IO_BUFFER_LITTLE_ENDIAN, swap16)
+ATOMIC_LOAD_IMPL(s16, int16_t, atomic_int_least16_t, 16, NUM2INT, INT2NUM, RB_IO_BUFFER_LITTLE_ENDIAN, swap16)
+ATOMIC_LOAD_IMPL(U16, uint16_t, atomic_uint_least16_t, 16, NUM2UINT, UINT2NUM, RB_IO_BUFFER_BIG_ENDIAN, swap16)
+ATOMIC_LOAD_IMPL(S16, int16_t, atomic_int_least16_t, 16, NUM2INT, INT2NUM, RB_IO_BUFFER_BIG_ENDIAN, swap16)
+
+// 32-bit types
+ATOMIC_LOAD_IMPL(u32, uint32_t, atomic_uint_least32_t, 32, NUM2UINT, UINT2NUM, RB_IO_BUFFER_LITTLE_ENDIAN, swap32)
+ATOMIC_LOAD_IMPL(s32, int32_t, atomic_int_least32_t, 32, NUM2INT, INT2NUM, RB_IO_BUFFER_LITTLE_ENDIAN, swap32)
+ATOMIC_LOAD_IMPL(U32, uint32_t, atomic_uint_least32_t, 32, NUM2UINT, UINT2NUM, RB_IO_BUFFER_BIG_ENDIAN, swap32)
+ATOMIC_LOAD_IMPL(S32, int32_t, atomic_int_least32_t, 32, NUM2INT, INT2NUM, RB_IO_BUFFER_BIG_ENDIAN, swap32)
+
+// 64-bit types
+ATOMIC_LOAD_IMPL(u64, uint64_t, atomic_uint_least64_t, 64, NUM2ULL, ULL2NUM, RB_IO_BUFFER_LITTLE_ENDIAN, swap64)
+ATOMIC_LOAD_IMPL(s64, int64_t, atomic_int_least64_t, 64, NUM2LL, LL2NUM, RB_IO_BUFFER_LITTLE_ENDIAN, swap64)
+ATOMIC_LOAD_IMPL(U64, uint64_t, atomic_uint_least64_t, 64, NUM2ULL, ULL2NUM, RB_IO_BUFFER_BIG_ENDIAN, swap64)
+ATOMIC_LOAD_IMPL(S64, int64_t, atomic_int_least64_t, 64, NUM2LL, LL2NUM, RB_IO_BUFFER_BIG_ENDIAN, swap64)
+
+ATOMIC_STORE_IMPL(U8, uint8_t, atomic_uint_least8_t, 8, NUM2UINT, UINT2NUM, RB_IO_BUFFER_BIG_ENDIAN, NULL)
+ATOMIC_STORE_IMPL(S8, int8_t, atomic_int_least8_t, 8, NUM2INT, INT2NUM, RB_IO_BUFFER_BIG_ENDIAN, NULL)
+
+ATOMIC_STORE_IMPL(u16, uint16_t, atomic_uint_least16_t, 16, NUM2UINT, UINT2NUM, RB_IO_BUFFER_LITTLE_ENDIAN, swap16)
+ATOMIC_STORE_IMPL(s16, int16_t, atomic_int_least16_t, 16, NUM2INT, INT2NUM, RB_IO_BUFFER_LITTLE_ENDIAN, swap16)
+ATOMIC_STORE_IMPL(U16, uint16_t, atomic_uint_least16_t, 16, NUM2UINT, UINT2NUM, RB_IO_BUFFER_BIG_ENDIAN, swap16)
+ATOMIC_STORE_IMPL(S16, int16_t, atomic_int_least16_t, 16, NUM2INT, INT2NUM, RB_IO_BUFFER_BIG_ENDIAN, swap16)
+
+ATOMIC_STORE_IMPL(u32, uint32_t, atomic_uint_least32_t, 32, NUM2UINT, UINT2NUM, RB_IO_BUFFER_LITTLE_ENDIAN, swap32)
+ATOMIC_STORE_IMPL(s32, int32_t, atomic_int_least32_t, 32, NUM2INT, INT2NUM, RB_IO_BUFFER_LITTLE_ENDIAN, swap32)
+ATOMIC_STORE_IMPL(U32, uint32_t, atomic_uint_least32_t, 32, NUM2UINT, UINT2NUM, RB_IO_BUFFER_BIG_ENDIAN, swap32)
+ATOMIC_STORE_IMPL(S32, int32_t, atomic_int_least32_t, 32, NUM2INT, INT2NUM, RB_IO_BUFFER_BIG_ENDIAN, swap32)
+
+ATOMIC_STORE_IMPL(u64, uint64_t, atomic_uint_least64_t, 64, NUM2ULL, ULL2NUM, RB_IO_BUFFER_LITTLE_ENDIAN, swap64)
+ATOMIC_STORE_IMPL(s64, int64_t, atomic_int_least64_t, 64, NUM2LL, LL2NUM, RB_IO_BUFFER_LITTLE_ENDIAN, swap64)
+ATOMIC_STORE_IMPL(U64, uint64_t, atomic_uint_least64_t, 64, NUM2ULL, ULL2NUM, RB_IO_BUFFER_BIG_ENDIAN, swap64)
+ATOMIC_STORE_IMPL(S64, int64_t, atomic_int_least64_t, 64, NUM2LL, LL2NUM, RB_IO_BUFFER_BIG_ENDIAN, swap64)
+
 ATOMIC_CAS_IMPL(u8, uint8_t, atomic_uint_least8_t, 1, NUM2UINT, UINT2NUM)
 ATOMIC_CAS_IMPL(i8, int8_t, atomic_int_least8_t, 1, NUM2INT, INT2NUM)
 ATOMIC_CAS_IMPL(u16, uint16_t, atomic_uint_least16_t, 2, NUM2UINT, UINT2NUM)
@@ -242,6 +333,58 @@ static VALUE atomic_xor_impl(VALUE self, ID type_identifier, size_t offset, long
 	return Qnil;
 }
 
+static VALUE atomic_load_impl(VALUE self, ID type_identifier, size_t offset) {
+#define ATOMIC_LOAD_CASE(name, impl_name) \
+	if (type_identifier == RB_IO_BUFFER_DATA_TYPE_##name) { \
+		return atomic_load_##impl_name(self, offset); \
+	}
+	
+	ATOMIC_LOAD_CASE(U8, U8)
+	ATOMIC_LOAD_CASE(S8, S8)
+	ATOMIC_LOAD_CASE(u16, u16)
+	ATOMIC_LOAD_CASE(s16, s16)
+	ATOMIC_LOAD_CASE(U16, U16)
+	ATOMIC_LOAD_CASE(S16, S16)
+	ATOMIC_LOAD_CASE(u32, u32)
+	ATOMIC_LOAD_CASE(s32, s32)
+	ATOMIC_LOAD_CASE(U32, U32)
+	ATOMIC_LOAD_CASE(S32, S32)
+	ATOMIC_LOAD_CASE(u64, u64)
+	ATOMIC_LOAD_CASE(s64, s64)
+	ATOMIC_LOAD_CASE(U64, U64)
+	ATOMIC_LOAD_CASE(S64, S64)
+#undef ATOMIC_LOAD_CASE
+	
+	rb_raise(rb_eArgError, "Unsupported type for atomic operations: %"PRIsVALUE, rb_id2str(type_identifier));
+	return Qnil;
+}
+
+static VALUE atomic_store_impl(VALUE self, ID type_identifier, size_t offset, VALUE value) {
+#define ATOMIC_STORE_CASE(name, impl_name) \
+	if (type_identifier == RB_IO_BUFFER_DATA_TYPE_##name) { \
+		return atomic_store_##impl_name(self, offset, value); \
+	}
+	
+	ATOMIC_STORE_CASE(U8, U8)
+	ATOMIC_STORE_CASE(S8, S8)
+	ATOMIC_STORE_CASE(u16, u16)
+	ATOMIC_STORE_CASE(s16, s16)
+	ATOMIC_STORE_CASE(U16, U16)
+	ATOMIC_STORE_CASE(S16, S16)
+	ATOMIC_STORE_CASE(u32, u32)
+	ATOMIC_STORE_CASE(s32, s32)
+	ATOMIC_STORE_CASE(U32, U32)
+	ATOMIC_STORE_CASE(S32, S32)
+	ATOMIC_STORE_CASE(u64, u64)
+	ATOMIC_STORE_CASE(s64, s64)
+	ATOMIC_STORE_CASE(U64, U64)
+	ATOMIC_STORE_CASE(S64, S64)
+#undef ATOMIC_STORE_CASE
+	
+	rb_raise(rb_eArgError, "Unsupported type for atomic operations: %"PRIsVALUE, rb_id2str(type_identifier));
+	return Qnil;
+}
+
 static VALUE atomic_compare_and_swap_impl(VALUE self, ID type_identifier, size_t offset, VALUE expected_value, VALUE desired_value) {
 #define ATOMIC_CAS_CASE(name, impl_name) \
 	if (type_identifier == RB_IO_BUFFER_DATA_TYPE_##name) { \
@@ -347,6 +490,20 @@ static VALUE atomic_xor(VALUE self, VALUE type_symbol, VALUE offset_value, VALUE
 	return atomic_xor_impl(self, type_identifier, offset, value);
 }
 
+static VALUE atomic_load_method(VALUE self, VALUE type_symbol, VALUE offset_value) {
+	ID type_identifier = get_type_id(type_symbol);
+	size_t offset = NUM2SIZET(offset_value);
+	
+	return atomic_load_impl(self, type_identifier, offset);
+}
+
+static VALUE atomic_store_method(VALUE self, VALUE type_symbol, VALUE offset_value, VALUE value) {
+	ID type_identifier = get_type_id(type_symbol);
+	size_t offset = NUM2SIZET(offset_value);
+	
+	return atomic_store_impl(self, type_identifier, offset, value);
+}
+
 static VALUE atomic_compare_and_swap(VALUE self, VALUE type_symbol, VALUE offset_value, VALUE expected_value, VALUE desired_value) {
 	ID type_identifier = get_type_id(type_symbol);
 	size_t offset = NUM2SIZET(offset_value);
@@ -371,7 +528,7 @@ void Init_IO_Buffer_Atomic(void) {
 
 	VALUE IO_Buffer = rb_const_get(rb_cIO, rb_intern("Buffer"));
 
-	// Initialize type IDs (matching Ruby's pattern)
+	// Initialize type IDs (support both forms for compatibility, but atomic operations work on raw bytes in host endian)
 #define IO_BUFFER_DEFINE_DATA_TYPE(name) RB_IO_BUFFER_DATA_TYPE_##name = rb_intern_const(#name)
 	IO_BUFFER_DEFINE_DATA_TYPE(U8);
 	IO_BUFFER_DEFINE_DATA_TYPE(S8);
@@ -396,5 +553,7 @@ void Init_IO_Buffer_Atomic(void) {
 	DEFINE_METHOD_IF_NOT_EXISTS(IO_Buffer, "atomic_and", atomic_and, 3);
 	DEFINE_METHOD_IF_NOT_EXISTS(IO_Buffer, "atomic_or", atomic_or, 3);
 	DEFINE_METHOD_IF_NOT_EXISTS(IO_Buffer, "atomic_xor", atomic_xor, 3);
+	DEFINE_METHOD_IF_NOT_EXISTS(IO_Buffer, "atomic_load", atomic_load_method, 2);
+	DEFINE_METHOD_IF_NOT_EXISTS(IO_Buffer, "atomic_store", atomic_store_method, 3);
 	DEFINE_METHOD_IF_NOT_EXISTS(IO_Buffer, "atomic_compare_and_swap", atomic_compare_and_swap, 4);
 }

guides/getting-started/readme.md

@@ -14,6 +14,8 @@ $ bundle add io-buffer-atomic
 
 `io-buffer-atomic` extends `IO::Buffer` with atomic operations that are safe for concurrent access across threads and processes. When multiple threads or processes share memory (via `IO::Buffer`), you need atomic operations to prevent race conditions and ensure data consistency.
 
+**Important**: Atomic operations work on raw memory bytes in host endian (native byte order). The endianness distinction in Ruby's type system (`:u32` vs `:U32`) affects how Ruby interprets bytes when reading/writing, but atomic operations themselves operate directly on raw memory in host byte order.
+
 Use atomic operations when you need:
 - **Thread-safe counters**: Multiple threads updating shared counters without locks.
 - **Process-safe coordination**: Multiple processes coordinating via shared memory.
@@ -77,6 +79,36 @@ result = buffer.atomic_xor(:u32, 0, 0b1111)
 # => 0b0000
 ```
 
+### Atomic Load
+
+Atomic load operations ensure you read a complete, consistent value from shared memory, preventing torn reads:
+
+```ruby
+# Set a value:
+buffer.set_value(:u32, 0, 42)
+
+# Atomically read the value (ensures no torn reads):
+result = buffer.atomic_load(:u32, 0)
+# => 42
+```
+
+Use `atomic_load` instead of `get_value` when reading values that may be modified by other threads or processes, as it provides memory ordering guarantees and prevents data races.
+
+### Atomic Store
+
+Atomic store operations ensure you write a complete value atomically to shared memory:
+
+```ruby
+# Atomically write a value:
+buffer.atomic_store(:u32, 0, 42)
+
+# Read it back:
+result = buffer.atomic_load(:u32, 0)
+# => 42
+```
+
+Use `atomic_store` instead of `set_value` when writing values that may be read by other threads or processes, as it provides memory ordering guarantees and prevents torn writes.
+
 ### Compare and Swap
 
 Compare-and-swap operations enable lock-free algorithms and optimistic concurrency:
@@ -88,7 +120,7 @@ buffer.set_value(:u32, 0, 10)
 # Atomically swap if current value matches expected:
 swapped = buffer.atomic_compare_and_swap(:u32, 0, 10, 20)
 # => true
-buffer.get_value(:u32, 0)
+buffer.atomic_load(:u32, 0)
 # => 20
 
 # If value doesn't match, swap fails:
@@ -98,6 +130,8 @@ swapped = buffer.atomic_compare_and_swap(:u32, 0, 10, 30)
 
 ## Supported Operations
 
+- `atomic_load(type, offset)` - Atomically read a value (prevents torn reads).
+- `atomic_store(type, offset, value)` - Atomically write a value (prevents torn writes).
 - `atomic_increment(type, offset, value = 1)` - Atomically increment a value.
 - `atomic_decrement(type, offset, value = 1)` - Atomically decrement a value.
 - `atomic_add(type, offset, value)` - Atomically add a value.
@@ -106,8 +140,3 @@ swapped = buffer.atomic_compare_and_swap(:u32, 0, 10, 30)
 - `atomic_or(type, offset, value)` - Atomically perform bitwise OR.
 - `atomic_xor(type, offset, value)` - Atomically perform bitwise XOR.
 - `atomic_compare_and_swap(type, offset, expected, desired)` - Atomically compare and swap.
-
-## Requirements
-
-- Ruby \>= 3.2.6.
-- `IO::Buffer` support (available in Ruby 3.2+).