Barriers: A Rendezvous That Survives Change
A barrier holds every party until the last one arrives. Learn how it counts and what a new threshold does to the parties already waiting. Then keep it right when one of them leaves for good.
You Will Be Able To
- Predict when
wait_forreleases, with auto-reset on and off. - Predict what
set_threshold,resetandcanceldo to processes already waiting. - Remove a lane from a running rendezvous without an early release or a hang.
- Use named barriers and a timeout without leaving the count wrong.
- Lesson
- U17.3
- Time
- 35 min
- Runs on
- Verilator with UVM
- Check
- 4 questions
Four lanes must start each burst in the same clock, so they meet at a barrier with a threshold of 4. A test stops lane C halfway through. One fix lowers the threshold to 3, and lanes A, B and D drift a round apart without a single error. Doing nothing instead hangs the test in round 3.
- Cycle 0
Round 1: the last lane, D, arrives at 9 ns and all four start together.
- Cycle 1
C arrives first in round 2 and is killed at 24 ns while it waits. The barrier still counts it.
- Cycle 2
Only
canceland then a lower threshold keep A, B and D together. The other two responses hang or split the lanes.
Measured by the example below. "Hangs" means the scenario gave up 100 ns after the kill.
How wait_for Counts
A uvm_barrier keeps a threshold, a count of waiting processes, an auto-reset flag and one internal uvm_event. wait_for() adds one to the count. If the count is still below the threshold, the caller waits on the internal event. The arrival that reaches the threshold triggers that event, sets the count back to 0 and returns.
Every waiter is released in the same time step. The last arrival waits one #0 before it returns, so that the others resume first. That is why the last lane's line is never printed first in the example.
wait_for() travels along them; the release comes back.- Step
- Control / FSM
- Control
- Three arrive4-7 ns (illustrative)
A, C and B arrive. The count goes 1, 2, 3, and each waits on the internal event.
Follow the calls, values and waits
- call count 1: Lane A → burst barrier
- call count 2: Lane C → burst barrier
- call count 3: Lane B → burst barrier
- Waiting: Lane A — waiting
- Waiting: Lane B — waiting
- Waiting: Lane C — waiting
- The fourth arrives9 ns (illustrative)
D makes the count 4. It triggers the event and sets the count to 0.
Follow the calls, values and waits
- call count 4: trigger: Lane D → burst barrier
- All four start9 ns (illustrative)
A, B and C resume. D waits one
#0, then returns too. With auto-reset on, the next arrival starts round 2.Follow the calls, values and waits
- return release: burst barrier → Lane A
- return release: burst barrier → Lane B
- return release: burst barrier → Lane C
- return return: burst barrier → Lane D
- Released: Lane A
- Released: Lane B
- Released: Lane C
Read the diagram as text
- Lane A: arrives at 4 ns
- Lane B: arrives at 7 ns
- Lane C: arrives at 5 ns
- Lane D: arrives at 9 ns
- burst barrier: threshold 4, a count, an event
- Lane A → burst barrier: wait_for()
- Lane B → burst barrier: wait_for()
- Lane C → burst barrier: wait_for()
- Lane D → burst barrier: wait_for()
The count lives in the barrier, not in the lanes. Anything that changes who will arrive must change the count or the threshold too.
With auto-reset on, the default, the barrier is ready for the next round at once. set_auto_reset(0) makes it a one-shot gate. After the first release it stays open, and every later wait_for returns at once until reset.
Changing the Threshold While Lanes Wait
set_threshold(n) takes effect at once. Raising it while lanes wait makes them wait for more arrivals. Lowering it to the count or below calls reset(1), which triggers the internal event and releases every waiter.
In uvm-core 2020.3.1 the release happens when the new threshold is equal to the count or below it. The standard covers both cases (1800.2 §10.3.2.6). Once the threshold is reached every waiter is released, and a threshold below the count also resets the barrier. The predict question below measures the case where the two are equal. So lowering a threshold is a release, not a setting, and is safe only when you know who is waiting.
A Lane That Leaves
Lanes leave for real reasons. A test disables one, a lane hits an error and stops, or a reset kills its thread. The barrier knows none of this. If the lane was waiting, it is still in the count. If it was not, it will simply never arrive. Either way the threshold is now one too high.
The example kills lane C at 24 ns, while C waits in round 2, and compares three responses.
| What the test does | Round 2 | Round 3 | Why |
|---|---|---|---|
| Nothing | A, B and D at 25 ns | Hangs with 3 waiting | Dead C still counts in round 2, so the 3 live lanes make 4. In round 3 they can never make 4. |
set_threshold(3) | B and D at 24 ns, A at 40 ns | B and D at 40 ns, then A hangs | B, C and D already make 3, so lowering releases them at once. A becomes the first arrival of a new round. |
cancel(), then set_threshold(3) | A, B and D at 25 ns | A, B and D at 41 ns | The count drops to 2, so A's arrival makes 3. |
Measured by the example. Neither of the first two responses reports an error: one hangs and one quietly splits the lanes.
cancel() takes one waiter out of the count. It is only bookkeeping: it wakes nobody, and it cannot tell which process left. So the rule has two parts. If the leaving lane was inside wait_for, cancel once. In every case, lower the threshold by one. Cancelling for a lane that was not waiting is just as wrong, because it removes a live waiter.
Reset and the One-Shot Gate
reset(wakeup) sets the count to 0 and leaves the threshold alone. With wakeup = 1, the barrier's default, it triggers the internal event, so every waiter is released. Use it when a round is abandoned, for example at a design reset.
With wakeup = 0, it resets the internal event instead. That is the event reset from U17.1, with the same problem: what happens to the waiters depends on the simulator. They are no longer counted, though, so the barrier has lost track of them. Never use reset(0) on a barrier with waiters.
| Call | Count | Threshold | Waiting processes |
|---|---|---|---|
set_threshold(n), n above the count | unchanged | n | keep waiting |
set_threshold(n), n at or below the count | 0 | n | released |
reset(1) | 0 | unchanged | released |
reset(0) | 0 | unchanged | no longer counted; release depends on the simulator |
cancel() | minus 1 | unchanged | unchanged |
set_auto_reset(0) | unchanged | unchanged | later callers pass once it has released |
uvm-core 2020.3.1, base/uvm_barrier.svh.
Who Owns the Threshold
A barrier works only if its threshold always equals the number of parties that will still arrive. That number changes whenever a lane is added, disabled or killed. So give the threshold one owner: usually the virtual sequence or the environment that starts and stops the lanes. Lanes themselves never touch it.
The owner also decides what a lane that leaves means for the others. Sometimes the round should go on without it, as in the example. Sometimes the whole round is now invalid, and reset(1) is the honest answer: release everyone, then let each lane decide what to do. Write that decision down next to the barrier, because the barrier itself will never report it.
Barriers are also the wrong tool in some places. When one party announces and the others listen, use an event. When the end of the test must wait for every lane to drain, an objection per lane is simpler. A barrier is for the case where everyone must arrive before anyone continues.
Named Barriers and Timeouts
uvm_barrier_pool::get_global("burst") returns the barrier with that name and creates it on first use, like the event pool in U17.2. A new barrier has threshold 0, and a threshold of 0 lets every caller through at once. So one component must own each named barrier. It sets the threshold in a build or connect phase, before any lane can call wait_for.
A rendezvous that can hang needs a timeout. Wrap wait_for in a fork with a timer. If the timer wins, disable the waiting branch and call cancel(), because that waiter is gone. Then report an error, so that a hang becomes a message with a name and a time.
task automatic meet(uvm_barrier bar, time limit, string who);
bit arrived = 0;
fork begin
fork
begin bar.wait_for(); arrived = 1; end
#(limit);
join_any
disable fork;
end join
if (!arrived) begin
bar.cancel(); // our wait_for was cut off
`uvm_error("RENDEZVOUS", $sformatf("%s waited %0t at %s", who, limit, bar.get_name()))
end
endtaskUVM books say little about barriers; the Cookbook only names them as a tool for advanced synchronisation. Everything here comes from the uvm-core source and the standard, checked by the runs.
Try It
Four scenarios, each on a new barrier. In the last three, lane C is killed at 24 ns while it waits in round 2. The test then does nothing, lowers the threshold, or cancels and then lowers it. A scenario gives up 100 ns after the kill. Lines within one time step can come in any order.
Try two edits. Change the third scenario's response to "cancel", and its rounds line up. Then move the kill to 18 ns, while C is still bursting, and decide which response is right. C has not arrived, so there is nothing to cancel.
--- all four lanes 9 ns round 1 D starts its burst 41 ns round 3 D starts its burst --- C killed, nothing done 24 ns C killed, barrier holds 3 waiter(s) 24 ns fix 'none': threshold 4, waiters 3 25 ns round 2 A starts its burst 124 ns gave up: 3 lane(s) still waiting --- C killed, threshold lowered 24 ns C killed, barrier holds 3 waiter(s) 24 ns fix 'lower': threshold 3, waiters 0 24 ns round 2 B starts its burst 24 ns round 2 D starts its burst 40 ns round 2 A starts its burst 40 ns round 3 B starts its burst 40 ns round 3 D starts its burst 124 ns gave up: 1 lane(s) still waiting --- C killed, cancel then lower 24 ns fix 'cancel': threshold 3, waiters 2 25 ns round 2 A starts its burst 41 ns round 3 D starts its burstCheck Yourself
Common Mistakes
Wrong Kill a waiting lane and only lower the threshold.
The dead lane is still counted. With the lower threshold the barrier releases one arrival early.
Fix Take the dead waiter out of the count before you lower the threshold.
Wrong Call cancel() for a lane that was not waiting.
It removes a live waiter from the count, so the round releases one arrival early.
Fix Cancel only when the lane was inside wait_for. Always lower the threshold.
Wrong Use a barrier from uvm_barrier_pool before anyone sets its threshold.
The pool creates the barrier with threshold 0, so every wait_for returns at once.
Fix Let one owner set the threshold before any party can arrive.
Remember
- A barrier counts arrivals and releases them all when the count reaches the threshold. Auto-reset re-arms it;
set_auto_reset(0)latches it open. - Lowering the threshold to the count or below is a release, not just a setting.
- When a lane leaves for good, cancel only if it was waiting, and always lower the threshold.
- A pool barrier starts at threshold 0, so one owner sets it before any lane arrives.
- Put a timeout and a
cancelaround every rendezvous that can hang.