std: Rename TailQueue to DoublyLinkedList

`TailQueue` was implemented as a doubly-linked list, but named after an
abstract data type. This was inconsistent with `SinglyLinkedList`, which
can be used to implement an abstract data type, but is still named after
the implementation. Renaming `TailQueue` to `DoublyLinkedList` improves
consistency between the two type names, and should help discoverability.

`TailQueue` is now a deprecated alias of `DoublyLinkedList`.

Related to issues #1629 and #8233.

Author: jayschwa

lib/std/atomic/queue.zig

@@ -14,7 +14,7 @@ pub fn Queue(comptime T: type) type {
         mutex: std.Thread.Mutex,
 
         pub const Self = @This();
-        pub const Node = std.TailQueue(T).Node;
+        pub const Node = std.DoublyLinkedList(T).Node;
 
         /// Initializes a new queue. The queue does not provide a `deinit()`
         /// function, so the user must take care of cleaning up the queue elements.

lib/std/http/Client.zig

@@ -36,7 +36,7 @@ pub const ConnectionPool = struct {
         is_tls: bool,
     };
 
-    const Queue = std.TailQueue(Connection);
+    const Queue = std.DoublyLinkedList(Connection);
     pub const Node = Queue.Node;
 
     mutex: std.Thread.Mutex = .{},

lib/std/linked_list.zig

@@ -4,7 +4,7 @@ const assert = debug.assert;
 const testing = std.testing;
 
 /// A singly-linked list is headed by a single forward pointer. The elements
-/// are singly linked for minimum space and pointer manipulation overhead at
+/// are singly-linked for minimum space and pointer manipulation overhead at
 /// the expense of O(n) removal for arbitrary elements. New elements can be
 /// added to the list after an existing element or at the head of the list.
 /// A singly-linked list may only be traversed in the forward direction.
@@ -171,13 +171,20 @@ test "basic SinglyLinkedList test" {
     try testing.expect(list.first.?.next.?.next == null);
 }
 
-/// A tail queue is headed by a pair of pointers, one to the head of the
-/// list and the other to the tail of the list. The elements are doubly
-/// linked so that an arbitrary element can be removed without a need to
-/// traverse the list. New elements can be added to the list before or
-/// after an existing element, at the head of the list, or at the end of
-/// the list. A tail queue may be traversed in either direction.
-pub fn TailQueue(comptime T: type) type {
+/// deprecated: use `DoublyLinkedList`.
+pub const TailQueue = DoublyLinkedList;
+
+/// A doubly-linked list has a pair of pointers to both the head and
+/// tail of the list. List elements have pointers to both the previous
+/// and next elements in the sequence. The list can be traversed both
+/// forward and backward. Some operations that take linear O(n) time
+/// with a singly-linked list can be done without traversal in constant
+/// O(1) time with a doubly-linked list:
+///
+/// - Removing an element.
+/// - Inserting a new element before an existing element.
+/// - Pushing or popping an element from the end of the list.
+pub fn DoublyLinkedList(comptime T: type) type {
     return struct {
         const Self = @This();
 
@@ -336,8 +343,8 @@ pub fn TailQueue(comptime T: type) type {
     };
 }
 
-test "basic TailQueue test" {
-    const L = TailQueue(u32);
+test "basic DoublyLinkedList test" {
+    const L = DoublyLinkedList(u32);
     var list = L{};
 
     var one = L.Node{ .data = 1 };
@@ -381,8 +388,8 @@ test "basic TailQueue test" {
     try testing.expect(list.len == 2);
 }
 
-test "TailQueue concatenation" {
-    const L = TailQueue(u32);
+test "DoublyLinkedList concatenation" {
+    const L = DoublyLinkedList(u32);
     var list1 = L{};
     var list2 = L{};
 

lib/std/std.zig

@@ -43,7 +43,7 @@ pub const StringHashMap = hash_map.StringHashMap;
 pub const StringHashMapUnmanaged = hash_map.StringHashMapUnmanaged;
 pub const StringArrayHashMap = array_hash_map.StringArrayHashMap;
 pub const StringArrayHashMapUnmanaged = array_hash_map.StringArrayHashMapUnmanaged;
-pub const TailQueue = @import("linked_list.zig").TailQueue;
+pub const DoublyLinkedList = @import("linked_list.zig").DoublyLinkedList;
 pub const Target = @import("target.zig").Target;
 pub const Thread = @import("Thread.zig");
 pub const Treap = @import("treap.zig").Treap;

src/Package.zig

@@ -130,17 +130,17 @@ pub fn add(pkg: *Package, gpa: Allocator, name: []const u8, package: *Package) !
 /// package. It should only be used for error output.
 pub fn getName(target: *const Package, gpa: Allocator, mod: Module) ![]const u8 {
     // we'll do a breadth-first search from the root module to try and find a short name for this
-    // module, using a TailQueue of module/parent pairs. note that the "parent" there is just the
-    // first-found shortest path - a module may be children of arbitrarily many other modules.
-    // also, this path may vary between executions due to hashmap iteration order, but that doesn't
-    // matter too much.
+    // module, using a DoublyLinkedList of module/parent pairs. note that the "parent" there is
+    // just the first-found shortest path - a module may be children of arbitrarily many other
+    // modules. This path may vary between executions due to hashmap iteration order, but that
+    // doesn't matter too much.
     var node_arena = std.heap.ArenaAllocator.init(gpa);
     defer node_arena.deinit();
     const Parented = struct {
         parent: ?*const @This(),
         mod: *const Package,
     };
-    const Queue = std.TailQueue(Parented);
+    const Queue = std.DoublyLinkedList(Parented);
     var to_check: Queue = .{};
 
     {

test/behavior/bugs/1735.zig

@@ -4,7 +4,7 @@ const builtin = @import("builtin");
 const mystruct = struct {
     pending: ?listofstructs,
 };
-pub fn TailQueue(comptime T: type) type {
+pub fn DoublyLinkedList(comptime T: type) type {
     return struct {
         const Self = @This();
 
@@ -27,7 +27,7 @@ pub fn TailQueue(comptime T: type) type {
         }
     };
 }
-const listofstructs = TailQueue(mystruct);
+const listofstructs = DoublyLinkedList(mystruct);
 
 const a = struct {
     const Self = @This();