Skip to content

Commit 7f9f1d1

Browse files
authored
fix(runtime): preserve stored partial bitstrings
Partial-byte bitstrings stored in ETS and persistent_term retain their exact values after writer exit or garbage collection. Copying reads remain valid after storage removal, including row updates that copy their contents. Equal bitstrings remain interchangeable as keys, and bag tables suppress duplicate rows after copying.
1 parent 3f67461 commit 7f9f1d1

6 files changed

Lines changed: 377 additions & 12 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,21 @@
22

33
All notable milestones for the nera project are documented in this file.
44

5+
## Stored bitstrings keep their bytes and exact bit length
6+
7+
- ETS and `persistent_term` now own copies of non-byte-aligned bitstrings,
8+
just as they already do for whole-byte binaries. Small inline values and
9+
large reference-counted values remain equal after the storing process exits
10+
or collects garbage, as on BEAM.
11+
- Copying reads preserve the final partial byte's logical bit length and remain
12+
valid after the table is deleted or the persistent term is erased.
13+
- Bitstring keys and bag duplicate checks compare significant bits and exact
14+
length, not descriptor addresses or unused trailing bits, so copies remain
15+
interchangeable as keys, including inside lists and tuples.
16+
- The `ets_stored_bitstring` and `ets_bitstring_keys` regressions exercise
17+
writer lifetimes, copying reads, boxed updates and copied-key operations
18+
unchanged natively and on BEAM.
19+
520
## Receives nested in after bodies resume at their own wait
621

722
- A `receive` directly inside another receive's `after` body now waits for

‎crates/nera-runtime/src/ets.rs‎

Lines changed: 30 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -221,13 +221,20 @@ impl TermKey {
221221
out.extend_from_slice(&term.0.to_le_bytes());
222222
return;
223223
}
224-
// Binary — serialize content bytes
225-
if term.is_binary() {
224+
// Bitstring identity is its exact length and significant bits, not
225+
// the descriptor address or unused bits in the final backing byte.
226+
if term.is_bitstring() {
226227
out.push(b'B');
227228
if let Some((ptr, len)) = unsafe { crate::ffi::binary_data_pub(term) } {
228229
let slice = unsafe { std::slice::from_raw_parts(ptr, len) };
229-
out.extend_from_slice(&(len as u64).to_le_bytes());
230-
out.extend_from_slice(slice);
230+
let bits = unsafe { term.binary_bit_size().unwrap() };
231+
out.extend_from_slice(&(bits as u64).to_le_bytes());
232+
let whole_bytes = bits / 8;
233+
out.extend_from_slice(&slice[..whole_bytes]);
234+
let trailing_bits = bits % 8;
235+
if trailing_bits != 0 {
236+
out.push(slice[whole_bytes] & (u8::MAX << (8 - trailing_bits)));
237+
}
231238
}
232239
return;
233240
}
@@ -402,7 +409,7 @@ unsafe fn object_heap_words(term: ErlTerm, pending: &mut WorkStack<ErlTerm>) ->
402409
queue(cursor); // tail
403410
return count;
404411
}
405-
if term.is_binary() {
412+
if term.is_bitstring() {
406413
if let Some((_ptr, len)) = unsafe { crate::ffi::binary_data_pub(term) } {
407414
if len <= REFC_BINARY_THRESHOLD {
408415
return 1 + len.div_ceil(8); // header + data words
@@ -517,7 +524,7 @@ trait CopyTarget {
517524
/// Allocate `n` uninitialized words that stay in place.
518525
fn alloc_words(&mut self, n: usize) -> *mut u64;
519526

520-
/// Copy a boxed term that holds no other terms (a binary, float, bigint
527+
/// Copy a boxed term that holds no other terms (a bitstring, float, bigint
521528
/// or reference); any other term is kept as it is.
522529
/// # Safety
523530
/// As for `deep_copy_into_compact`.
@@ -536,16 +543,17 @@ impl CopyTarget for CompactHeap {
536543
REFC_BINARY_OFFSET_WORD_INDEX, REFERENCE_TOTAL_WORDS,
537544
REFERENCE_ID_WORD_INDEX};
538545

539-
if term.is_binary() {
546+
if term.is_bitstring() {
540547
if let Some((ptr, len)) = unsafe { crate::ffi::binary_data_pub(term) } {
541548
let bytes = unsafe { std::slice::from_raw_parts(ptr, len) };
549+
let bit_len = unsafe { term.binary_bit_size().unwrap() } as u64;
542550
if len <= REFC_BINARY_THRESHOLD {
543551
// Inline heap binary: [header | data words...]
544552
let data_words = len.div_ceil(8);
545553
let total_words = 1 + data_words;
546554
let words = self.alloc_words(total_words);
547555
unsafe {
548-
*words = BoxedHeader::new(crate::term::BoxedSubtype::HeapBinary, (len * 8) as u64).0;
556+
*words = BoxedHeader::new(crate::term::BoxedSubtype::HeapBinary, bit_len).0;
549557
std::ptr::copy_nonoverlapping(
550558
bytes.as_ptr(),
551559
(words.add(1)) as *mut u8,
@@ -559,7 +567,7 @@ impl CopyTarget for CompactHeap {
559567
let raw_arc_ptr = Arc::as_ptr(&data) as u64;
560568
let words = self.alloc_words(REFC_BINARY_TOTAL_WORDS);
561569
unsafe {
562-
*words = BoxedHeader::new(crate::term::BoxedSubtype::RefcBinary, (len * 8) as u64).0;
570+
*words = BoxedHeader::new(crate::term::BoxedSubtype::RefcBinary, bit_len).0;
563571
*words.add(REFC_BINARY_PTR_WORD_INDEX) = raw_arc_ptr;
564572
*words.add(REFC_BINARY_OFFSET_WORD_INDEX) = 0;
565573
}
@@ -613,10 +621,16 @@ impl CopyTarget for ProcessHeap {
613621
}
614622

615623
unsafe fn copy_leaf(&mut self, term: ErlTerm) -> ErlTerm {
616-
if term.is_binary() {
624+
if term.is_bitstring() {
617625
if let Some((ptr, len)) = unsafe { crate::ffi::binary_data_pub(term) } {
618626
let bytes = unsafe { std::slice::from_raw_parts(ptr, len) };
619-
return self.alloc_binary_auto(bytes);
627+
let bit_len = unsafe { term.binary_bit_size().unwrap() } as u64;
628+
let copy = self.alloc_binary_auto(bytes);
629+
// Allocation rounds up to bytes; preserve the logical bit
630+
// length rather than turning the trailing bits into a byte.
631+
let header = copy.as_boxed_ptr().unwrap().cast_mut();
632+
unsafe { *header = BoxedHeader(*header).with_arity(bit_len).0; }
633+
return copy;
620634
}
621635
return term;
622636
}
@@ -690,7 +704,7 @@ impl<'a, T: CopyTarget> EtsCopier<'a, T> {
690704
if term.is_cons() {
691705
return unsafe { self.copy_list(term) };
692706
}
693-
if !unsafe { term.is_binary() } {
707+
if !unsafe { term.is_bitstring() } {
694708
if let Some(ptr) = term.as_boxed_ptr() {
695709
let header = BoxedHeader(unsafe { *ptr });
696710
let (subtype, raw, slots) = match header.subtype() {
@@ -3781,3 +3795,7 @@ mod tests {
37813795
}
37823796
}
37833797
}
3798+
3799+
#[cfg(test)]
3800+
#[path = "ets_bitstring_tests.rs"]
3801+
mod bitstring_tests;
Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
//! Focused invariants for the bitstring storage regressions. The Erlang
2+
//! fixtures own observable lifetime/key behavior; these tests deterministically
3+
//! check descriptor independence and insignificant backing-byte padding.
4+
5+
use super::*;
6+
use crate::binary::BinarySlice;
7+
use crate::term::BoxedSubtype;
8+
9+
#[test]
10+
fn bitstring_copies_own_descriptors_in_both_directions() {
11+
// The reported values, plus a sub-byte value and the inline/refc boundary.
12+
let mut large = vec![b'x'; 200];
13+
large.push(0xc0); // <<3:2>>
14+
let mut boundary = vec![b'b'; crate::heap::REFC_BINARY_THRESHOLD];
15+
boundary.push(0x80); // <<1:1>>
16+
let cases = [
17+
(b"abcdefgh\x50".to_vec(), 4),
18+
(large, 6),
19+
(vec![0xa0], 5),
20+
(boundary, 7),
21+
];
22+
23+
for (bytes, unused_bits) in cases {
24+
let bits = bytes.len() * 8 - unused_bits;
25+
for refc_window in [false, true] {
26+
let mut source = ProcessHeap::new();
27+
let original = if refc_window {
28+
// A byte-offset window must not accidentally copy its prefix.
29+
let prefix = b"prefix";
30+
let backing = [prefix.as_slice(), &bytes, b"suffix"].concat();
31+
let window =
32+
BinarySlice::new_bits(Arc::new(BinaryData::new(backing)), prefix.len(), bits)
33+
.unwrap();
34+
source.alloc_binary_slice(window)
35+
} else {
36+
let term = source.alloc_binary(&bytes);
37+
// SAFETY: the test exclusively owns the new descriptor and
38+
// shortens its bit length within its initialized byte storage.
39+
unsafe {
40+
*term.as_boxed_ptr().unwrap().cast_mut() =
41+
BoxedHeader::new(BoxedSubtype::HeapBinary, bits as u64).0;
42+
}
43+
term
44+
};
45+
46+
// SAFETY: the source is live, immutable and cannot collect here.
47+
let words = unsafe { count_heap_words(original) };
48+
let mut pool = EtsRegionPool::new();
49+
let mut stored = CompactHeap::from_pool(Some(pool.alloc(words)));
50+
let in_storage = unsafe { deep_copy_into_compact(original, &mut stored) };
51+
assert_ne!(
52+
in_storage.as_boxed_ptr(),
53+
original.as_boxed_ptr(),
54+
"storage must own the bitstring descriptor"
55+
);
56+
drop(source);
57+
58+
let mut reader = ProcessHeap::new();
59+
// SAFETY: stored keeps every source descriptor/backing byte live.
60+
let read = unsafe { deep_copy_into_heap(in_storage, &mut reader) };
61+
assert_ne!(
62+
read.as_boxed_ptr(),
63+
in_storage.as_boxed_ptr(),
64+
"copying reads must own the bitstring descriptor"
65+
);
66+
drop(stored);
67+
drop(pool);
68+
69+
let mut roots = [read];
70+
// SAFETY: the sole root belongs to reader; no raw borrows survive.
71+
unsafe { reader.collect_full(&mut roots) };
72+
// SAFETY: the root was updated by GC and reader owns its bytes.
73+
unsafe {
74+
assert_eq!(roots[0].binary_bit_size(), Some(bits));
75+
assert_eq!(roots[0].binary_bytes_any(), Some(bytes.as_slice()));
76+
}
77+
}
78+
}
79+
}
80+
81+
// Storage copies must not turn equal bitstring keys into
82+
// address-based keys. A real byte window can retain bits beyond its logical end.
83+
#[test]
84+
fn bitstring_keys_ignore_padding_but_preserve_significant_bits_and_length() {
85+
let mut heap = ProcessHeap::new();
86+
let bytes = b"abcdefghP"; // Last byte's high nibble is <<5:4>>.
87+
let bits = bytes.len() * 8 - 4;
88+
let make_heap_bits = |heap: &mut ProcessHeap, data: &[u8], bits: usize| {
89+
let term = heap.alloc_binary(data);
90+
// SAFETY: the test exclusively owns the descriptor and only shortens
91+
// its bit window within initialized bytes.
92+
unsafe {
93+
*term.as_boxed_ptr().unwrap().cast_mut() =
94+
BoxedHeader::new(BoxedSubtype::HeapBinary, bits as u64).0;
95+
}
96+
term
97+
};
98+
let original = make_heap_bits(&mut heap, bytes, bits);
99+
let prefix = b"prefix";
100+
let framed = [prefix.as_slice(), b"abcdefghZ", b"suffix"].concat();
101+
let window =
102+
BinarySlice::new_bits(Arc::new(BinaryData::new(framed)), prefix.len(), bits).unwrap();
103+
let same_bits = heap.alloc_binary_slice(window);
104+
let different_bits = make_heap_bits(&mut heap, b"abcdefgh@", bits);
105+
let different_length = make_heap_bits(&mut heap, bytes, bits + 1);
106+
let whole_bytes = heap.alloc_binary(bytes);
107+
108+
// SAFETY: heap keeps all immutable input descriptors and bytes live.
109+
unsafe {
110+
let key = TermKey::from_term(original);
111+
assert!(key == TermKey::from_term(same_bits));
112+
assert!(key != TermKey::from_term(different_bits));
113+
assert!(key != TermKey::from_term(different_length));
114+
assert!(key != TermKey::from_term(whole_bytes));
115+
}
116+
}

‎tests/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -462,6 +462,8 @@ These are automatically skipped by the runner and show up as SKIP in output.
462462
| `ets_basic.erl` | ETS new/insert/lookup/delete/tab2list | ~15 |
463463
| `ets_keypos.erl` | ETS keypos and named tables | ~8 |
464464
| `ets_stored_fun.erl` | A fun stored in ETS (at the top of a row, nested in a list, tuple and map, after `update_element/3`) or `persistent_term` by a process that then exits or collects garbage keeps its captured list, binaries, tuple, map, float, bignum and inner fun when looked up and called; a fun read by `tab2list/1` or `persistent_term:get/1` still works after the table or term is deleted; completion marker; also run on BEAM | ~16 |
465+
| `ets_stored_bitstring.erl` | Non-byte-aligned heap/refc bitstrings, sub-byte values and extracted tails stored in ETS or `persistent_term` survive writer exit/GC; boxed `update_element/3` replacements and copying reads remain intact after table deletion or term erasure; completion marker; same fixture on BEAM | 4 lifetime scenarios |
466+
| `ets_bitstring_keys.erl` | Partial-bitstring bag duplicate suppression; copied direct/list/tuple keys in hash-backed tables for lookup, membership, insert_new, boxed updates, counters, deletion and forward/backward traversal; copied values as persistent_term keys; significant bits and exact lengths remain distinct; completion marker; same fixture on BEAM | Table-driven |
465467
| `ets_named_table_return.erl` | ets:new/2 with `named_table` returns the name (Cowboy's `?MODULE = ets:new(?MODULE, [named_table, ...])`): every table type, apply, variable module and fun calls; a table without `named_table` does not take the name, and creating or deleting one leaves a named table with the same atom reachable; the name is released by ets:delete/1; a table created in another process is reached by its name; also run on BEAM | Table-driven |
466468

467469
### Stdlib

‎tests/ets_bitstring_keys.erl‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
%% EXPECT: ets_bitstring_keys_ok
2+
%% Regression for storage copies exposing pointer-based bitstring keys.
3+
%% Returned/copied keys and bag values must still compare by significant bits,
4+
%% including bitstrings nested in lists and tuples. Run unchanged on BEAM.
5+
-module(ets_bitstring_keys).
6+
-export([test/0]).
7+
8+
test() ->
9+
bag_duplicates(),
10+
[table_keys(Type) || Type <- [set, bag, duplicate_bag]],
11+
persistent_keys(),
12+
io:format("ets_bitstring_keys_ok~n"),
13+
ok.
14+
15+
keys() ->
16+
Small = <<"abcdefgh", (id(5)):4>>,
17+
Bytes = list_to_binary(lists:duplicate(id(200), $x)),
18+
Large = <<Bytes/binary, (id(3)):2>>,
19+
[Small, Large, [Small], {wrapped, [Large, Small]},
20+
<<(id(5)):3>>, <<(id(20)):5>>, <<(id(4)):3>>].
21+
22+
id(X) -> X.
23+
24+
bag_duplicates() ->
25+
[Small, Large | _] = keys(),
26+
Value = {Small, [Large, Small]},
27+
T = ets:new(bitstring_bag, [bag]),
28+
Row = {key, Value},
29+
true = ets:insert(T, Row),
30+
true = ets:insert(T, Row),
31+
[Row] = ets:lookup(T, key),
32+
true = ets:delete(T),
33+
ok.
34+
35+
table_keys(Type) ->
36+
T = ets:new(bitstring_keys, [Type]),
37+
Keys = keys(),
38+
[true = ets:insert(T, {K, 0, unchanged}) || K <- Keys],
39+
CopiedRows = ets:tab2list(T),
40+
Count = length(Keys),
41+
Count = length(CopiedRows),
42+
[check_copied_key(Type, T, Row) || Row <- CopiedRows],
43+
Sorted = lists:sort(Keys),
44+
Sorted = lists:sort(walk(T, ets:first(T), next)),
45+
Sorted = lists:sort(walk(T, ets:last(T), prev)),
46+
%% Keys from traversal also work for lookup and membership.
47+
true = ets:member(T, ets:first(T)),
48+
true = ets:member(T, ets:last(T)),
49+
[begin
50+
true = ets:delete(T, K),
51+
false = ets:member(T, K),
52+
[] = ets:lookup(T, K)
53+
end || {K, _, _} <- CopiedRows],
54+
[] = ets:tab2list(T),
55+
true = ets:delete(T),
56+
ok.
57+
58+
check_copied_key(Type, T, {K, 0, unchanged}) ->
59+
true = ets:member(T, K),
60+
[{K, 0, unchanged}] = ets:lookup(T, K),
61+
false = ets:insert_new(T, {K, 99, replaced}),
62+
case Type of
63+
set ->
64+
true = ets:update_element(T, K, {3, [updated]}),
65+
1 = ets:update_counter(T, K, {2, 1}),
66+
[{K, 1, [updated]}] = ets:lookup(T, K);
67+
_ -> ok
68+
end,
69+
ok.
70+
71+
walk(_T, '$end_of_table', _Direction) -> [];
72+
walk(T, K, Direction) ->
73+
[_] = ets:lookup(T, K),
74+
Next = case Direction of
75+
next -> ets:next(T, K);
76+
prev -> ets:prev(T, K)
77+
end,
78+
[K | walk(T, Next, Direction)].
79+
80+
persistent_keys() ->
81+
CopyKey = {?MODULE, copied_key},
82+
[begin
83+
%% Reading a stored value makes a new descriptor, which must be
84+
%% interchangeable with the original when either is used as a key.
85+
ok = persistent_term:put(CopyKey, K),
86+
Copied = persistent_term:get(CopyKey),
87+
ok = persistent_term:put(K, original),
88+
original = persistent_term:get(Copied),
89+
ok = persistent_term:put(Copied, replaced),
90+
replaced = persistent_term:get(K),
91+
true = persistent_term:erase(Copied),
92+
missing = persistent_term:get(K, missing)
93+
end || K <- keys()],
94+
true = persistent_term:erase(CopyKey),
95+
ok.

0 commit comments

Comments
 (0)