authorgravatar for jay@jayschwa.netJay Petacat <jay@jayschwa.net> 2023-08-27 16:06:39-06:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2023-08-27 20:57:46-07:00
logff61c428793ff382c8d521638b416ca288e53de5
treee0a10146c9f2f74d6e816e08764a5d1b8ff05d44
parent750998eef62a70dbea8c3ba1d44245f506370911

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.

6 files changed, 29 insertions(+), 22 deletions(-)

lib/std/atomic/queue.zig+1-1
...@@ -14,7 +14,7 @@ pub fn Queue(comptime T: type) type {...@@ -14,7 +14,7 @@ pub fn Queue(comptime T: type) type {
14 mutex: std.Thread.Mutex,14 mutex: std.Thread.Mutex,
1515
16 pub const Self = @This();16 pub const Self = @This();
17 pub const Node = std.TailQueue(T).Node;17 pub const Node = std.DoublyLinkedList(T).Node;
1818
19 /// Initializes a new queue. The queue does not provide a `deinit()`19 /// Initializes a new queue. The queue does not provide a `deinit()`
20 /// function, so the user must take care of cleaning up the queue elements.20 /// function, so the user must take care of cleaning up the queue elements.
lib/std/http/Client.zig+1-1
...@@ -36,7 +36,7 @@ pub const ConnectionPool = struct {...@@ -36,7 +36,7 @@ pub const ConnectionPool = struct {
36 is_tls: bool,36 is_tls: bool,
37 };37 };
3838
39 const Queue = std.TailQueue(Connection);39 const Queue = std.DoublyLinkedList(Connection);
40 pub const Node = Queue.Node;40 pub const Node = Queue.Node;
4141
42 mutex: std.Thread.Mutex = .{},42 mutex: std.Thread.Mutex = .{},
lib/std/linked_list.zig+19-12
...@@ -4,7 +4,7 @@ const assert = debug.assert;...@@ -4,7 +4,7 @@ const assert = debug.assert;
4const testing = std.testing;4const testing = std.testing;
55
6/// A singly-linked list is headed by a single forward pointer. The elements6/// A singly-linked list is headed by a single forward pointer. The elements
7/// are singly linked for minimum space and pointer manipulation overhead at7/// are singly-linked for minimum space and pointer manipulation overhead at
8/// the expense of O(n) removal for arbitrary elements. New elements can be8/// the expense of O(n) removal for arbitrary elements. New elements can be
9/// added to the list after an existing element or at the head of the list.9/// added to the list after an existing element or at the head of the list.
10/// A singly-linked list may only be traversed in the forward direction.10/// A singly-linked list may only be traversed in the forward direction.
...@@ -171,13 +171,20 @@ test "basic SinglyLinkedList test" {...@@ -171,13 +171,20 @@ test "basic SinglyLinkedList test" {
171 try testing.expect(list.first.?.next.?.next == null);171 try testing.expect(list.first.?.next.?.next == null);
172}172}
173173
174/// A tail queue is headed by a pair of pointers, one to the head of the174/// deprecated: use `DoublyLinkedList`.
175/// list and the other to the tail of the list. The elements are doubly175pub const TailQueue = DoublyLinkedList;
176/// linked so that an arbitrary element can be removed without a need to176
177/// traverse the list. New elements can be added to the list before or177/// A doubly-linked list has a pair of pointers to both the head and
178/// after an existing element, at the head of the list, or at the end of178/// tail of the list. List elements have pointers to both the previous
179/// the list. A tail queue may be traversed in either direction.179/// and next elements in the sequence. The list can be traversed both
180pub fn TailQueue(comptime T: type) type {180/// forward and backward. Some operations that take linear O(n) time
181/// with a singly-linked list can be done without traversal in constant
182/// O(1) time with a doubly-linked list:
183///
184/// - Removing an element.
185/// - Inserting a new element before an existing element.
186/// - Pushing or popping an element from the end of the list.
187pub fn DoublyLinkedList(comptime T: type) type {
181 return struct {188 return struct {
182 const Self = @This();189 const Self = @This();
183190
...@@ -336,8 +343,8 @@ pub fn TailQueue(comptime T: type) type {...@@ -336,8 +343,8 @@ pub fn TailQueue(comptime T: type) type {
336 };343 };
337}344}
338345
339test "basic TailQueue test" {346test "basic DoublyLinkedList test" {
340 const L = TailQueue(u32);347 const L = DoublyLinkedList(u32);
341 var list = L{};348 var list = L{};
342349
343 var one = L.Node{ .data = 1 };350 var one = L.Node{ .data = 1 };
...@@ -381,8 +388,8 @@ test "basic TailQueue test" {...@@ -381,8 +388,8 @@ test "basic TailQueue test" {
381 try testing.expect(list.len == 2);388 try testing.expect(list.len == 2);
382}389}
383390
384test "TailQueue concatenation" {391test "DoublyLinkedList concatenation" {
385 const L = TailQueue(u32);392 const L = DoublyLinkedList(u32);
386 var list1 = L{};393 var list1 = L{};
387 var list2 = L{};394 var list2 = L{};
388395
lib/std/std.zig+1-1
...@@ -43,7 +43,7 @@ pub const StringHashMap = hash_map.StringHashMap;...@@ -43,7 +43,7 @@ pub const StringHashMap = hash_map.StringHashMap;
43pub const StringHashMapUnmanaged = hash_map.StringHashMapUnmanaged;43pub const StringHashMapUnmanaged = hash_map.StringHashMapUnmanaged;
44pub const StringArrayHashMap = array_hash_map.StringArrayHashMap;44pub const StringArrayHashMap = array_hash_map.StringArrayHashMap;
45pub const StringArrayHashMapUnmanaged = array_hash_map.StringArrayHashMapUnmanaged;45pub const StringArrayHashMapUnmanaged = array_hash_map.StringArrayHashMapUnmanaged;
46pub const TailQueue = @import("linked_list.zig").TailQueue;46pub const DoublyLinkedList = @import("linked_list.zig").DoublyLinkedList;
47pub const Target = @import("target.zig").Target;47pub const Target = @import("target.zig").Target;
48pub const Thread = @import("Thread.zig");48pub const Thread = @import("Thread.zig");
49pub const Treap = @import("treap.zig").Treap;49pub const Treap = @import("treap.zig").Treap;
src/Package.zig+5-5
...@@ -130,17 +130,17 @@ pub fn add(pkg: *Package, gpa: Allocator, name: []const u8, package: *Package) !...@@ -130,17 +130,17 @@ pub fn add(pkg: *Package, gpa: Allocator, name: []const u8, package: *Package) !
130/// package. It should only be used for error output.130/// package. It should only be used for error output.
131pub fn getName(target: *const Package, gpa: Allocator, mod: Module) ![]const u8 {131pub fn getName(target: *const Package, gpa: Allocator, mod: Module) ![]const u8 {
132 // we'll do a breadth-first search from the root module to try and find a short name for this132 // we'll do a breadth-first search from the root module to try and find a short name for this
133 // module, using a TailQueue of module/parent pairs. note that the "parent" there is just the133 // module, using a DoublyLinkedList of module/parent pairs. note that the "parent" there is
134 // first-found shortest path - a module may be children of arbitrarily many other modules.134 // just the first-found shortest path - a module may be children of arbitrarily many other
135 // also, this path may vary between executions due to hashmap iteration order, but that doesn't135 // modules. This path may vary between executions due to hashmap iteration order, but that
136 // matter too much.136 // doesn't matter too much.
137 var node_arena = std.heap.ArenaAllocator.init(gpa);137 var node_arena = std.heap.ArenaAllocator.init(gpa);
138 defer node_arena.deinit();138 defer node_arena.deinit();
139 const Parented = struct {139 const Parented = struct {
140 parent: ?*const @This(),140 parent: ?*const @This(),
141 mod: *const Package,141 mod: *const Package,
142 };142 };
143 const Queue = std.TailQueue(Parented);143 const Queue = std.DoublyLinkedList(Parented);
144 var to_check: Queue = .{};144 var to_check: Queue = .{};
145145
146 {146 {
test/behavior/bugs/1735.zig+2-2
...@@ -4,7 +4,7 @@ const builtin = @import("builtin");...@@ -4,7 +4,7 @@ const builtin = @import("builtin");
4const mystruct = struct {4const mystruct = struct {
5 pending: ?listofstructs,5 pending: ?listofstructs,
6};6};
7pub fn TailQueue(comptime T: type) type {7pub fn DoublyLinkedList(comptime T: type) type {
8 return struct {8 return struct {
9 const Self = @This();9 const Self = @This();
1010
...@@ -27,7 +27,7 @@ pub fn TailQueue(comptime T: type) type {...@@ -27,7 +27,7 @@ pub fn TailQueue(comptime T: type) type {
27 }27 }
28 };28 };
29}29}
30const listofstructs = TailQueue(mystruct);30const listofstructs = DoublyLinkedList(mystruct);
3131
32const a = struct {32const a = struct {
33 const Self = @This();33 const Self = @This();