Skip to content

Commit 9c6da14

Browse files
authored
fix(runtime): keep messages between two processes in send order
A message sent to a process is never received before the messages the same sender sent it earlier. The receive_nil_message test no longer fails intermittently. A new end-to-end fixture checks message order between processes, natively and on BEAM.
1 parent 2b5d015 commit 9c6da14

7 files changed

Lines changed: 228 additions & 30 deletions

File tree

‎CHANGELOG.md‎

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

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

5+
## Messages between two processes arrive in the order they were sent
6+
7+
- A message one process sends another is now always received after the
8+
messages that process sent it earlier, as on BEAM. Previously a later
9+
message could be received first: when it was sent while the receiver was
10+
between two runs, it went straight into the receiver's mailbox, ahead of
11+
an earlier message that was still waiting to be moved there. The
12+
`receive_nil_message` fixture failed this way now and then, receiving
13+
`[[], [], e]` instead of `[[], e, []]`.
14+
- Programs that run on BEAM are unaffected.
15+
- The `send_order_between_processes` fixture streams numbered messages
16+
between several pairs of processes and checks their order, natively and
17+
on BEAM.
18+
519
## Sending and storing deeply nested terms
620

721
- A term nested hundreds of thousands of levels deep, such as an iolist

‎crates/nera-runtime/src/ffi/process.rs‎

Lines changed: 108 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -111,19 +111,14 @@ pub unsafe extern "C" fn nera_rt_send_message(ctx: *mut ProcessContext, pid_term
111111
});
112112
if let Some(entry) = entry {
113113
// Try direct-to-heap send when the target process is not being
114-
// executed by any worker. This bypasses the SegQueue entirely,
115-
// eliminating fragment allocation + copy-to-heap overhead.
116-
use crate::process::{ASTATUS_WAITING, ASTATUS_READY};
117-
let status = entry.published_status();
118-
let direct_sent = if status == ASTATUS_WAITING || status == ASTATUS_READY {
119-
if let Some(mut proc) = entry.try_lock_for_runtime() {
120-
let copied = direct_copy_message(ErlTerm(msg), &mut proc.heap);
121-
proc.mailbox.send(copied);
122-
drop(proc);
123-
true
124-
} else {
125-
false
126-
}
114+
// executed by any worker and has nothing queued in its inbox.
115+
// This bypasses the SegQueue entirely, eliminating fragment
116+
// allocation + copy-to-heap overhead.
117+
let direct_sent = if let Some(mut proc) = entry.try_lock_for_direct_send() {
118+
let copied = direct_copy_message(ErlTerm(msg), &mut proc.heap);
119+
proc.mailbox.send(copied);
120+
drop(proc);
121+
true
127122
} else {
128123
false
129124
};
@@ -397,17 +392,12 @@ pub unsafe extern "C" fn nera_rt_send_tuple(
397392
};
398393

399394
if let Some(entry) = entry {
400-
use crate::process::{ASTATUS_WAITING, ASTATUS_READY};
401-
let status = entry.published_status();
402-
let direct_sent = if status == ASTATUS_WAITING || status == ASTATUS_READY {
403-
if let Some(mut proc) = entry.try_lock_for_runtime() {
404-
let tuple = build_tuple_on_heap(&mut proc.heap, arity, &raw_elems, true);
405-
proc.mailbox.send(tuple);
406-
drop(proc);
407-
true
408-
} else {
409-
false
410-
}
395+
// As in nera_rt_send_message, a queued inbox keeps this send there.
396+
let direct_sent = if let Some(mut proc) = entry.try_lock_for_direct_send() {
397+
let tuple = build_tuple_on_heap(&mut proc.heap, arity, &raw_elems, true);
398+
proc.mailbox.send(tuple);
399+
drop(proc);
400+
true
411401
} else {
412402
false
413403
};
@@ -2414,6 +2404,100 @@ mod delivery_timer_tests {
24142404
}
24152405
}
24162406

2407+
#[cfg(test)]
2408+
mod delivery_order_tests {
2409+
use super::*;
2410+
use crate::process::{ProcessId, ProcessState, WaitReason};
2411+
use crate::scheduler::SchedulerHandle;
2412+
use std::sync::atomic::{AtomicI64, AtomicU32};
2413+
2414+
// The receive_nil_message end-to-end test sometimes got [[], [], e]
2415+
// instead of [[], e, []] on macOS arm64. A sender's first message went to
2416+
// the inbox of a running receiver. The receiver's worker then published
2417+
// its receive wait and released the lock, so the sender's second message
2418+
// took the direct path into the mailbox. The first one left the inbox
2419+
// only on the receiver's next run, behind the second.
2420+
fn received_after_two_sends(send: impl Fn(&mut ProcessContext, ProcessId, i64)) -> Vec<i64> {
2421+
#[cfg(mio_supported)]
2422+
let (reactor, reactor_thread) = crate::reactor::spawn_reactor();
2423+
let owner = Arc::new(SchedulerHandle {
2424+
injector: Arc::new(crossbeam_deque::Injector::new()),
2425+
process_table: Arc::new(dashmap::DashMap::new()),
2426+
next_pid: Arc::new(crate::process::ProcessIdAllocator::starting_at(2)),
2427+
runnable_count: Arc::new(AtomicI64::new(0)),
2428+
alive_count: Arc::new(AtomicI64::new(1)),
2429+
registered_names: Arc::new(parking_lot::RwLock::new(std::collections::HashMap::new())),
2430+
timer_wheel: Arc::new(crate::timer::TimerWheel::new()),
2431+
worker_notify: Arc::new((parking_lot::Mutex::new(()), parking_lot::Condvar::new())),
2432+
io_pool: Arc::new(crate::io_pool::IoPool::new(1)),
2433+
#[cfg(mio_supported)]
2434+
reactor: reactor.clone(),
2435+
worker_inboxes: Arc::new(Vec::new()),
2436+
num_workers: 0,
2437+
worker_threads: Arc::new(Vec::new()),
2438+
dispatch_rr: AtomicU32::new(0),
2439+
});
2440+
let receiver = ProcessId::new(4_243);
2441+
let entry = Arc::new(ProcessEntry::new(Process::new(receiver)));
2442+
owner.process_table.insert(receiver, Arc::clone(&entry));
2443+
let mut sender = ProcessContext::new(ProcessId::new(1));
2444+
sender.runtime = Arc::as_ptr(&owner);
2445+
// Forget any entry an earlier test on this thread cached for the PID.
2446+
SEND_CACHE.with(|cache| *cache.borrow_mut() = None);
2447+
2448+
// The receiver is running, so the first message waits in its inbox.
2449+
entry.lock_for_runtime().transition(ProcessState::Running);
2450+
send(&mut sender, receiver, 1);
2451+
assert_eq!(entry.inbox.len(), 1);
2452+
// Its worker publishes the receive wait and releases the lock while
2453+
// the first message is still in the inbox.
2454+
entry.lock_for_runtime().transition(ProcessState::Waiting(WaitReason::Receive {
2455+
timeout_deadline_ms: None,
2456+
}));
2457+
send(&mut sender, receiver, 2);
2458+
2459+
// The receiver's next run drains its inbox into the mailbox.
2460+
let mut proc = entry.lock_for_runtime();
2461+
proc.drain_inbox();
2462+
let received = proc.mailbox.messages().map(|message| {
2463+
let number = match message.as_boxed_ptr() {
2464+
// SAFETY: a boxed message is a 2-tuple on the heap of the
2465+
// receiver, which stays locked and alive here.
2466+
Some(tuple) => ErlTerm(unsafe { *tuple.add(2) }),
2467+
None => message,
2468+
};
2469+
number.as_small_int().expect("a numbered message")
2470+
}).collect();
2471+
drop(proc);
2472+
#[cfg(mio_supported)]
2473+
{
2474+
reactor.shutdown();
2475+
reactor_thread.join().unwrap();
2476+
}
2477+
received
2478+
}
2479+
2480+
#[test]
2481+
fn a_later_message_does_not_overtake_a_queued_one() {
2482+
let received = received_after_two_sends(|sender, receiver, n| {
2483+
// SAFETY: the sender context and its scheduler outlive the call;
2484+
// the message is an immediate, so no sender heap is read.
2485+
unsafe { nera_rt_send_message(sender, ErlTerm::pid(receiver).0, ErlTerm::small_int(n).0) };
2486+
});
2487+
assert_eq!(received, [1, 2]);
2488+
}
2489+
2490+
#[test]
2491+
fn a_later_tuple_does_not_overtake_a_queued_one() {
2492+
let received = received_after_two_sends(|sender, receiver, n| {
2493+
let tag = ErlTerm::atom(crate::atom_table::ATOM_OK).0;
2494+
// SAFETY: as above; both tuple elements are immediates.
2495+
unsafe { nera_rt_send_tuple(sender, ErlTerm::pid(receiver).0, 2, tag, ErlTerm::small_int(n).0, 0, 0) };
2496+
});
2497+
assert_eq!(received, [1, 2]);
2498+
}
2499+
}
2500+
24172501
#[cfg(test)]
24182502
mod send_tuple_tests {
24192503
use super::*;

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -396,6 +396,29 @@ impl ProcessEntry {
396396
self.try_lock().map(RuntimeProcessGuard)
397397
}
398398

399+
/// Lock a ready or receive-waiting process so a sender can append a
400+
/// message straight to its mailbox, bypassing the inbox.
401+
///
402+
/// Returns `None` when the sender must push to the inbox instead: the
403+
/// process is running, waiting for I/O or exited, another thread holds
404+
/// its lock, or its inbox still holds messages. Inbox messages reach the
405+
/// mailbox only when the process next runs, so a message appended
406+
/// directly would overtake them, including an earlier message from the
407+
/// same sender. Erlang delivers the messages one process sends another in
408+
/// the order they were sent.
409+
#[inline]
410+
pub(crate) fn try_lock_for_direct_send(&self) -> Option<RuntimeProcessGuard<'_>> {
411+
let status = self.published_status();
412+
if status != ASTATUS_WAITING && status != ASTATUS_READY {
413+
return None;
414+
}
415+
let guard = self.try_lock_for_runtime()?;
416+
// Only a lock holder drains the inbox, so while this guard is held
417+
// nothing is between the inbox and the mailbox, and the sender's own
418+
// earlier pushes are visible here.
419+
self.inbox.is_empty().then_some(guard)
420+
}
421+
399422
/// Attempt to wake a process waiting for a message via CAS (`Waiting → Ready`).
400423
/// Only wakes RECEIVE_WAIT processes — NOT IO_WAIT processes.
401424
/// Returns `true` if the transition succeeded.

‎docs/ARCHITECTURE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -331,7 +331,7 @@ Sender Process Receiver ProcessEntry
331331
```
332332

333333
- `ProcessEntry` wraps `inbox: SegQueue<MessageFragment>`, `atomic_status: AtomicU32`, `proc: Mutex<Process>`
334-
- **Direct-to-heap send** (fast path): `try_lock()` the target when WAITING/READY, copy directly to receiver's heap using `direct_copy_message` (skips HashMap forwarding for simple tuples). Falls back to SegQueue on contention
334+
- **Direct-to-heap send** (fast path): `try_lock()` the target when WAITING/READY and its inbox is empty, copy directly to receiver's heap using `direct_copy_message` (skips HashMap forwarding for simple tuples). Falls back to SegQueue on contention, and while the inbox holds messages so a later message never overtakes an earlier one from the same sender
335335
- **Lock-free send** (fallback): deep-copy to fragment → `inbox.push()` → CAS `WAITING→READY` → inject into scheduler + notify workers
336336
- **Fragment types**: `Immediate(ErlTerm)` for atoms/ints/PIDs/nil, `InlineTuple` (arity ≤ 2, zero alloc), `SimpleTuple` (Vec-backed), `Heap { heap, root }` for complex terms
337337
- **SendDirect fusion**: IR pass `fuse_make_tuple_send` detects `MakeTuple(msg, elems) + Send(result, pid, msg)` where `msg` is single-use, fuses into `SendDirect(result, pid, elems)`. Codegen emits `nera_rt_send_tuple` which constructs the tuple directly on the receiver's heap without sender heap allocation

‎docs/RUNTIME_DESIGN.md‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -585,11 +585,16 @@ table entirely, using batch allocation for tuple elements.
585585
fused sends, `nera_rt_send_tuple(ctx, pid, arity, e0, e1, e2, e3)`.
586586
2. The runtime resolves the target PID (or registered name) via the process
587587
table (with thread-local cache for repeated sends to the same PID).
588-
3. **Direct-to-heap** (fast path): If the target is WAITING or READY and
589-
`try_lock()` succeeds, the message is copied directly to the receiver's
590-
heap using `direct_copy_message()`. No fragment allocation needed.
591-
4. **Lock-free fragment** (fallback): On contention, a `MessageFragment` is
592-
created and pushed to the receiver's `SegQueue` inbox.
588+
3. **Direct-to-heap** (fast path): If the target is WAITING or READY,
589+
`try_lock()` succeeds and its inbox is empty, the message is copied
590+
directly to the receiver's heap using `direct_copy_message()`. No
591+
fragment allocation needed.
592+
4. **Lock-free fragment** (fallback): On contention, or while the inbox still
593+
holds messages, a `MessageFragment` is created and pushed to the
594+
receiver's `SegQueue` inbox. Inbox messages reach the mailbox only when
595+
the receiver next runs, so a direct copy would overtake them, including
596+
an earlier message from the same sender; Erlang delivers the messages
597+
between two processes in the order they were sent.
593598
5. If the target was in `Waiting` state, CAS transitions it to `Ready` and
594599
injects it into the scheduler's work queue.
595600
6. The send expression evaluates to the sent message (Erlang convention).

‎tests/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -339,6 +339,7 @@ These are automatically skipped by the runner and show up as SKIP in output.
339339
| `receive_after.erl` | Receive with timeout | ~4 |
340340
| `receive_timeout_domain.erl` | `after` values outside `infinity` and 0..4294967295: a matching queued message is received first, including selective receive and inside `try`; with no match, `error:timeout_value` at once, queued messages kept, no wait for a later sender, and as an uncaught exit; an error in the `after` expression or earlier in a `try` body comes first; valid boundaries; also run on BEAM | Table-driven |
341341
| `receive_nil_message.erl` | The message `[]` is received like any other: first, middle and last in the mailbox, `[]` patterns and guards, `after 0` and no `after`, selective receive skipping it, and a waiting process woken by it; later messages still arrive; also run on BEAM | ~21 |
342+
| `send_order_between_processes.erl` | Messages one process sends another arrive in the order they were sent: four senders each stream 100,000 numbers to their own receiver, and 2,000 bursts of three come back from an echo process in order; also run on BEAM | 3 |
342343
| `process_dict.erl` | put/get/erase/get_keys | ~10 |
343344
| `process_dict_exact_keys.erl` | put/get/erase exact numeric and compound keys, signed zeros, equal reconstructed keys, missing lookup/removal, replacement/erase returns, dictionary contents and direct/qualified/dynamic/fun calls; also run on BEAM | Table-driven |
344345
| `process_dict_get_keys.erl` | get_keys/1 exact value filtering, auto-import/qualified/dynamic/fun calls, dictionary preservation, arbitrary keys, updates/erase and Ranch child-state lookup; also run on BEAM | Table-driven |
Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
%% EXPECT: send_order_between_processes_ok
2+
%% Regression: the messages one process sends another arrive in the order
3+
%% they were sent, as on BEAM. Before the fix, a sender could append a
4+
%% message straight to the receiver's mailbox while its earlier message still
5+
%% waited in the receiver's queue of incoming messages, so the later message
6+
%% was received first. receive_nil_message failed this way now and then:
7+
%% [[], [], e] instead of [[], e, []]. Run this same fixture on native Nera
8+
%% and BEAM.
9+
-module(send_order_between_processes).
10+
-export([test/0]).
11+
12+
-define(PAIRS, 4).
13+
-define(MESSAGES, 100000).
14+
15+
test() ->
16+
%% Each sender streams 1..?MESSAGES to its own receiver while the others
17+
%% run, and each receiver counts the numbers that do not follow the one
18+
%% before. The senders run while their receivers are taking messages,
19+
%% waiting for the next one or being woken, so every delivery path is
20+
%% exercised.
21+
Main = self(),
22+
Receivers = [spawn(fun() -> receiver(Main, 0, 0) end)
23+
|| _ <- lists:seq(1, ?PAIRS)],
24+
[spawn(fun() -> sender(Receiver, 1) end) || Receiver <- Receivers],
25+
Results = [receive {Receiver, Last, OutOfOrder} -> {Last, OutOfOrder}
26+
after 20000 -> timeout end
27+
|| Receiver <- Receivers],
28+
Expected = lists:duplicate(?PAIRS, {?MESSAGES, 0}),
29+
Expected = Results,
30+
31+
%% The pattern receive_nil_message checks: a burst sent to an echo
32+
%% process comes back in the order it was sent, round after round.
33+
Echo = spawn(fun() -> echo(Main) end),
34+
ok = bursts(Echo, 2000),
35+
Echo ! stop,
36+
37+
io:format("send_order_between_processes_ok~n"),
38+
ok.
39+
40+
sender(_Receiver, N) when N > ?MESSAGES -> ok;
41+
sender(Receiver, N) ->
42+
Receiver ! N,
43+
sender(Receiver, N + 1).
44+
45+
%% Stop at the last number, whenever it arrives, and report how many
46+
%% numbers did not follow the previous one.
47+
receiver(Main, Last, OutOfOrder) ->
48+
receive
49+
N when N =:= ?MESSAGES ->
50+
Main ! {self(), N, count(N, Last, OutOfOrder)};
51+
N ->
52+
receiver(Main, N, count(N, Last, OutOfOrder))
53+
end.
54+
55+
count(N, Last, OutOfOrder) when N =:= Last + 1 -> OutOfOrder;
56+
count(_N, _Last, OutOfOrder) -> OutOfOrder + 1.
57+
58+
bursts(_Echo, 0) -> ok;
59+
bursts(Echo, Round) ->
60+
Echo ! {Round, 1},
61+
Echo ! {Round, 2},
62+
Echo ! {Round, 3},
63+
[{Round, 1}, {Round, 2}, {Round, 3}] =
64+
[receive {Echo, M} -> M after 1000 -> timeout end || _ <- [1, 2, 3]],
65+
bursts(Echo, Round - 1).
66+
67+
echo(Parent) ->
68+
receive
69+
stop -> ok;
70+
M -> Parent ! {self(), M}, echo(Parent)
71+
end.

0 commit comments

Comments
 (0)