Skip to content

Commit 5cb941b

Browse files
committed
Explains queue names vs. queue IDs
Clarifies the distinction between queue names and queue IDs, emphasizing that `Name` is the stable identifier used for data routing and sharing across processes, while `QueueId` is a runtime identifier used for logging. Adds a tip about sharing queues across processes by ensuring they use the same `Name`. Also adds a note that `InMemoryQueue` is an in-process only implementation.
1 parent 28da909 commit 5cb941b

File tree

1 file changed

+29
-0
lines changed

1 file changed

+29
-0
lines changed

docs/guide/queues.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,35 @@ public interface IQueue : IHaveSerializer, IDisposable
3838
}
3939
```
4040

41+
## Queue Name vs Queue ID
42+
43+
Every queue has two distinct identifiers that serve different purposes:
44+
45+
| Property | Purpose | Stable across restarts? | Shared across processes? |
46+
|----------|---------|------------------------|--------------------------|
47+
| `Name` | Identifies the queue in the **backing store** (Redis key prefix, SQS queue name, etc.) | ✅ Yes | ✅ Yes — two processes with the same `Name` share the same data |
48+
| `QueueId` | Runtime **instance identifier** used only for logging and diagnostics | ❌ No (random suffix by default) | N/A — never used for data routing |
49+
50+
**`Name`** is what controls which data is read and written. All distributed queue implementations (Redis, SQS, Azure Service Bus, Azure Storage) route messages based on `Name`, not `QueueId`. Two processes or application restarts using the same `Name` will naturally share queue data and continue from where the other left off.
51+
52+
**`QueueId`** exists purely so that multiple queue instances within the same process (e.g., priority queues or keyed queues) produce distinguishable log output. It has no effect on the backing store.
53+
54+
::: tip Sharing queues across processes
55+
If you want multiple processes (or application restarts) to share a queue, just ensure they all configure the same `Name` value. The default is `typeof(T).Name` (the message type name), so it is consistent by default as long as you use the same message type.
56+
57+
```csharp
58+
// Both processes use the same Name → they share the same queue in Redis
59+
var queue = new RedisQueue<WorkItem>(o => {
60+
o.ConnectionMultiplexer = redis;
61+
o.Name = "work-items"; // This is the stable backing-store identifier
62+
});
63+
```
64+
:::
65+
66+
::: info InMemoryQueue
67+
`InMemoryQueue` is an in-process implementation only. It cannot share data across processes regardless of `Name` or `QueueId`. Use a distributed implementation (Redis, SQS, Azure) for cross-process sharing.
68+
:::
69+
4170
## Implementations
4271

4372
### InMemoryQueue

0 commit comments

Comments
 (0)