Commit ff61c428793ff382c8d521638b416ca288e53de5 | zig

author	Jay Petacat <jay@jayschwa.net> 2023-08-27 16:06:39-06:00
committer	Andrew Kelley <andrew@ziglang.org> 2023-08-27 20:57:46-07:00
log	ff61c428793ff382c8d521638b416ca288e53de5
tree	e0a10146c9f2f74d6e816e08764a5d1b8ff05d44
parent	750998eef62a70dbea8c3ba1d44245f506370911

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
  - http
    Client.zig
  - linked_list.zig
  - std.zig
src
- Package.zig
test
- behavior
  - bugs
    1735.zig

lib/std/atomic/queue.zig+1-1

...	...	@@ -14,7 +14,7 @@ pub fn Queue(comptime T: type) type {
14	14	mutex: std.Thread.Mutex,
15	15
16	16	pub const Self = @This();
17		pub const Node = std.TailQueue(T).Node;
	17	pub const Node = std.DoublyLinkedList(T).Node;
18	18
19	19	/// Initializes a new queue. The queue does not provide a `deinit()`
20	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	36	is_tls: bool,
37	37	};
38	38
39		const Queue = std.TailQueue(Connection);
	39	const Queue = std.DoublyLinkedList(Connection);
40	40	pub const Node = Queue.Node;
41	41
42	42	mutex: std.Thread.Mutex = .{},

lib/std/linked_list.zig+19-12

...	...	@@ -4,7 +4,7 @@ const assert = debug.assert;
4	4	const testing = std.testing;
5	5
6	6	/// A singly-linked list is headed by a single forward pointer. The elements
7		/// are singly linked for minimum space and pointer manipulation overhead at
	7	/// are singly-linked for minimum space and pointer manipulation overhead at
8	8	/// the expense of O(n) removal for arbitrary elements. New elements can be
9	9	/// added to the list after an existing element or at the head of the list.
10	10	/// A singly-linked list may only be traversed in the forward direction.
...	...	@@ -171,13 +171,20 @@ test "basic SinglyLinkedList test" {
171	171	try testing.expect(list.first.?.next.?.next == null);
172	172	}
173	173
174		/// A tail queue is headed by a pair of pointers, one to the head of the
175		/// list and the other to the tail of the list. The elements are doubly
176		/// linked so that an arbitrary element can be removed without a need to
177		/// traverse the list. New elements can be added to the list before or
178		/// after an existing element, at the head of the list, or at the end of
179		/// the list. A tail queue may be traversed in either direction.
180		pub fn TailQueue(comptime T: type) type {
	174	/// deprecated: use `DoublyLinkedList`.
	175	pub const TailQueue = DoublyLinkedList;
	176
	177	/// A doubly-linked list has a pair of pointers to both the head and
	178	/// tail of the list. List elements have pointers to both the previous
	179	/// and next elements in the sequence. The list can be traversed both
	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.
	187	pub fn DoublyLinkedList(comptime T: type) type {
181	188	return struct {
182	189	const Self = @This();
183	190
...	...	@@ -336,8 +343,8 @@ pub fn TailQueue(comptime T: type) type {
336	343	};
337	344	}
338	345
339		test "basic TailQueue test" {
340		const L = TailQueue(u32);
	346	test "basic DoublyLinkedList test" {
	347	const L = DoublyLinkedList(u32);
341	348	var list = L{};
342	349
343	350	var one = L.Node{ .data = 1 };
...	...	@@ -381,8 +388,8 @@ test "basic TailQueue test" {
381	388	try testing.expect(list.len == 2);
382	389	}
383	390
384		test "TailQueue concatenation" {
385		const L = TailQueue(u32);
	391	test "DoublyLinkedList concatenation" {
	392	const L = DoublyLinkedList(u32);
386	393	var list1 = L{};
387	394	var list2 = L{};
388	395

lib/std/std.zig+1-1

...	...	@@ -43,7 +43,7 @@ pub const StringHashMap = hash_map.StringHashMap;
43	43	pub const StringHashMapUnmanaged = hash_map.StringHashMapUnmanaged;
44	44	pub const StringArrayHashMap = array_hash_map.StringArrayHashMap;
45	45	pub const StringArrayHashMapUnmanaged = array_hash_map.StringArrayHashMapUnmanaged;
46		pub const TailQueue = @import("linked_list.zig").TailQueue;
	46	pub const DoublyLinkedList = @import("linked_list.zig").DoublyLinkedList;
47	47	pub const Target = @import("target.zig").Target;
48	48	pub const Thread = @import("Thread.zig");
49	49	pub 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	130	/// package. It should only be used for error output.
131	131	pub fn getName(target: *const Package, gpa: Allocator, mod: Module) ![]const u8 {
132	132	// 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 the
134		// first-found shortest path - a module may be children of arbitrarily many other modules.
135		// also, this path may vary between executions due to hashmap iteration order, but that doesn't
136		// matter too much.
	133	// module, using a DoublyLinkedList of module/parent pairs. note that the "parent" there is
	134	// just the first-found shortest path - a module may be children of arbitrarily many other
	135	// modules. This path may vary between executions due to hashmap iteration order, but that
	136	// doesn't matter too much.
137	137	var node_arena = std.heap.ArenaAllocator.init(gpa);
138	138	defer node_arena.deinit();
139	139	const Parented = struct {
140	140	parent: ?*const @This(),
141	141	mod: *const Package,
142	142	};
143		const Queue = std.TailQueue(Parented);
	143	const Queue = std.DoublyLinkedList(Parented);
144	144	var to_check: Queue = .{};
145	145
146	146	{

test/behavior/bugs/1735.zig+2-2

...	...	@@ -4,7 +4,7 @@ const builtin = @import("builtin");
4	4	const mystruct = struct {
5	5	pending: ?listofstructs,
6	6	};
7		pub fn TailQueue(comptime T: type) type {
	7	pub fn DoublyLinkedList(comptime T: type) type {
8	8	return struct {
9	9	const Self = @This();
10	10
...	...	@@ -27,7 +27,7 @@ pub fn TailQueue(comptime T: type) type {
27	27	}
28	28	};
29	29	}
30		const listofstructs = TailQueue(mystruct);
	30	const listofstructs = DoublyLinkedList(mystruct);
31	31
32	32	const a = struct {
33	33	const Self = @This();