Commit 67eed9955005aaa02344b8d566ba140b9f2e0e18 | zig

author	Matthew Lugg <mlugg@mlugg.co.uk> 2025-12-15 11:24:26+00:00
committer	Matthew Lugg <mlugg@mlugg.co.uk> 2025-12-21 13:07:04+00:00
log	67eed9955005aaa02344b8d566ba140b9f2e0e18
tree	1f11358b2a1fd708738a93df52ff18175a7e2c7c
parent	fa7e818e144f2fd316fc54492f4699f6e1524738
signature	Commit is signed but in an unrecognized format.

std.Io.Queue: introduce closure and fix a bug

Queues can now be "closed". A closed queue cannot have more elements
appended with `put`, and blocked calls to `put` will immediately unblock
having failed to append some elements. Calls to `get` will continue to
succeed as long as the queue buffer is non-empty, but will then never
block; already-blocked calls to `get` will unblock.

All queue get/put operations can now return `error.Closed` to indicate
that the queue has been closed. For bulk get/put operations, they may
add/receive fewer elements than the minimum requested *if* the queue was
closed or the calling task was canceled. In that case, if any elements
were already added/received, they are returned first, and successive
calls will return `error.Closed` or `error.Canceled`.

Also, fix a bug where `Queue.get` could deadlock because it incorrectly
blocked until the given buffer was *filled*.

Resolves: #30141

5 files changed, 370 insertions(+), 164 deletions(-)

lib
- std
  - Io.zig
  - Io
    Threaded.zig
    net
    HostName.zig
    test.zig
    test.zig

lib/std/Io.zig+221-82

...	...	@@ -701,7 +701,7 @@ pub const VTable = struct {
701	701	netClose: const fn (?anyopaque, handle: net.Socket.Handle) void,
702	702	netInterfaceNameResolve: const fn (?anyopaque, *const net.Interface.Name) net.Interface.Name.ResolveError!net.Interface,
703	703	netInterfaceName: const fn (?anyopaque, net.Interface) net.Interface.NameError!net.Interface.Name,
704		netLookup: const fn (?anyopaque, net.HostName, *Queue(net.HostName.LookupResult), net.HostName.LookupOptions) void,
	704	netLookup: const fn (?anyopaque, net.HostName, *Queue(net.HostName.LookupResult), net.HostName.LookupOptions) net.HostName.LookupError!void,
705	705	};
706	706
707	707	pub const Cancelable = error{
...	...	@@ -1208,7 +1208,9 @@ pub fn Select(comptime U: type) type {
1208	1208	const args_casted: *const Args = @ptrCast(@alignCast(context));
1209	1209	const unerased_select: *S = @fieldParentPtr("group", group);
1210	1210	const elem = @unionInit(U, @tagName(field), @call(.auto, function, args_casted.*));
1211		unerased_select.queue.putOneUncancelable(unerased_select.io, elem);
	1211	unerased_select.queue.putOneUncancelable(unerased_select.io, elem) catch \|err\| switch (err) {
	1212	error.Closed => unreachable,
	1213	};
1212	1214	}
1213	1215	};
1214	1216	_ = @atomicRmw(usize, &s.outstanding, .Add, 1, .monotonic);
...	...	@@ -1222,7 +1224,10 @@ pub fn Select(comptime U: type) type {
1222	1224	/// Not threadsafe.
1223	1225	pub fn wait(s: *S) Cancelable!U {
1224	1226	s.outstanding -= 1;
1225		return s.queue.getOne(s.io);
	1227	return s.queue.getOne(s.io) catch \|err\| switch (err) {
	1228	error.Canceled => \|e\| return e,
	1229	error.Closed => unreachable,
	1230	};
1226	1231	}
1227	1232
1228	1233	/// Equivalent to `wait` but requests cancellation on all remaining
...	...	@@ -1569,8 +1574,11 @@ pub const Event = enum(u32) {
1569	1574	}
1570	1575	};
1571	1576
	1577	pub const QueueClosedError = error{Closed};
	1578
1572	1579	pub const TypeErasedQueue = struct {
1573	1580	mutex: Mutex,
	1581	closed: bool,
1574	1582
1575	1583	/// Ring buffer. This data is logically after queued getters.
1576	1584	buffer: []u8,
...	...	@@ -1582,12 +1590,14 @@ pub const TypeErasedQueue = struct {
1582	1590
1583	1591	const Put = struct {
1584	1592	remaining: []const u8,
	1593	needed: usize,
1585	1594	condition: Condition,
1586	1595	node: std.DoublyLinkedList.Node,
1587	1596	};
1588	1597
1589	1598	const Get = struct {
1590	1599	remaining: []u8,
	1600	needed: usize,
1591	1601	condition: Condition,
1592	1602	node: std.DoublyLinkedList.Node,
1593	1603	};
...	...	@@ -1595,6 +1605,7 @@ pub const TypeErasedQueue = struct {
1595	1605	pub fn init(buffer: []u8) TypeErasedQueue {
1596	1606	return .{
1597	1607	.mutex = .init,
	1608	.closed = false,
1598	1609	.buffer = buffer,
1599	1610	.start = 0,
1600	1611	.len = 0,
...	...	@@ -1603,7 +1614,27 @@ pub const TypeErasedQueue = struct {
1603	1614	};
1604	1615	}
1605	1616
1606		pub fn put(q: *TypeErasedQueue, io: Io, elements: []const u8, min: usize) Cancelable!usize {
	1617	pub fn close(q: *TypeErasedQueue, io: Io) void {
	1618	q.mutex.lockUncancelable(io);
	1619	defer q.mutex.unlock(io);
	1620	q.closed = true;
	1621	{
	1622	var it = q.getters.first;
	1623	while (it) \|node\| : (it = node.next) {
	1624	const getter: *Get = @alignCast(@fieldParentPtr("node", node));
	1625	getter.condition.signal(io);
	1626	}
	1627	}
	1628	{
	1629	var it = q.putters.first;
	1630	while (it) \|node\| : (it = node.next) {
	1631	const putter: *Put = @alignCast(@fieldParentPtr("node", node));
	1632	putter.condition.signal(io);
	1633	}
	1634	}
	1635	}
	1636
	1637	pub fn put(q: *TypeErasedQueue, io: Io, elements: []const u8, min: usize) (QueueClosedError \|\| Cancelable)!usize {
1607	1638	assert(elements.len >= min);
1608	1639	if (elements.len == 0) return 0;
1609	1640	try q.mutex.lock(io);
...	...	@@ -1614,13 +1645,14 @@ pub const TypeErasedQueue = struct {
1614	1645	/// Same as `put`, except does not introduce a cancelation point.
1615	1646	///
1616	1647	/// For a description of cancelation and cancelation points, see `Future.cancel`.
1617		pub fn putUncancelable(q: *TypeErasedQueue, io: Io, elements: []const u8, min: usize) usize {
	1648	pub fn putUncancelable(q: *TypeErasedQueue, io: Io, elements: []const u8, min: usize) QueueClosedError!usize {
1618	1649	assert(elements.len >= min);
1619	1650	if (elements.len == 0) return 0;
1620	1651	q.mutex.lockUncancelable(io);
1621	1652	defer q.mutex.unlock(io);
1622	1653	return q.putLocked(io, elements, min, true) catch \|err\| switch (err) {
1623	1654	error.Canceled => unreachable,
	1655	error.Closed => \|e\| return e,
1624	1656	};
1625	1657	}
1626	1658
...	...	@@ -1634,49 +1666,79 @@ pub const TypeErasedQueue = struct {
1634	1666	return if (slice.len > 0) slice else null;
1635	1667	}
1636	1668
1637		fn putLocked(q: *TypeErasedQueue, io: Io, elements: []const u8, min: usize, uncancelable: bool) Cancelable!usize {
	1669	fn putLocked(q: *TypeErasedQueue, io: Io, elements: []const u8, target: usize, uncancelable: bool) (QueueClosedError \|\| Cancelable)!usize {
	1670	// A closed queue cannot be added to, even if there is space in the buffer.
	1671	if (q.closed) return error.Closed;
	1672
1638	1673	// Getters have first priority on the data, and only when the getters
1639	1674	// queue is empty do we start populating the buffer.
1640	1675
1641		var remaining = elements;
	1676	// The number of elements we add immediately, before possibly blocking.
	1677	var n: usize = 0;
	1678
1642	1679	while (q.getters.popFirst()) \|getter_node\| {
1643	1680	const getter: *Get = @alignCast(@fieldParentPtr("node", getter_node));
1644		const copy_len = @min(getter.remaining.len, remaining.len);
	1681	const copy_len = @min(getter.remaining.len, elements.len - n);
1645	1682	assert(copy_len > 0);
1646		@memcpy(getter.remaining[0..copy_len], remaining[0..copy_len]);
1647		remaining = remaining[copy_len..];
	1683	@memcpy(getter.remaining[0..copy_len], elements[n..][0..copy_len]);
1648	1684	getter.remaining = getter.remaining[copy_len..];
1649		if (getter.remaining.len == 0) {
	1685	getter.needed -\|= copy_len;
	1686	n += copy_len;
	1687	if (getter.needed == 0) {
1650	1688	getter.condition.signal(io);
1651		if (remaining.len > 0) continue;
1652		} else q.getters.prepend(getter_node);
1653		assert(remaining.len == 0);
1654		return elements.len;
	1689	} else {
	1690	assert(n == elements.len); // we didn't have enough elements for the getter
	1691	q.getters.prepend(getter_node);
	1692	}
	1693	if (n == elements.len) return elements.len;
1655	1694	}
1656	1695
1657	1696	while (q.puttableSlice()) \|slice\| {
1658		const copy_len = @min(slice.len, remaining.len);
	1697	const copy_len = @min(slice.len, elements.len - n);
1659	1698	assert(copy_len > 0);
1660		@memcpy(slice[0..copy_len], remaining[0..copy_len]);
	1699	@memcpy(slice[0..copy_len], elements[n..][0..copy_len]);
1661	1700	q.len += copy_len;
1662		remaining = remaining[copy_len..];
1663		if (remaining.len == 0) return elements.len;
	1701	n += copy_len;
	1702	if (n == elements.len) return elements.len;
1664	1703	}
1665	1704
1666		const total_filled = elements.len - remaining.len;
1667		if (total_filled >= min) return total_filled;
	1705	// Don't block if we hit the target.
	1706	if (n >= target) return n;
1668	1707
1669		var pending: Put = .{ .remaining = remaining, .condition = .{}, .node = .{} };
	1708	var pending: Put = .{
	1709	.remaining = elements[n..],
	1710	.needed = target - n,
	1711	.condition = .init,
	1712	.node = .{},
	1713	};
1670	1714	q.putters.append(&pending.node);
1671		defer if (pending.remaining.len > 0) q.putters.remove(&pending.node);
1672		while (pending.remaining.len > 0) if (uncancelable)
1673		pending.condition.waitUncancelable(io, &q.mutex)
1674		else
1675		try pending.condition.wait(io, &q.mutex);
1676		return elements.len;
	1715	defer if (pending.needed > 0) q.putters.remove(&pending.node);
	1716
	1717	while (pending.needed > 0 and !q.closed) {
	1718	if (uncancelable) {
	1719	pending.condition.waitUncancelable(io, &q.mutex);
	1720	continue;
	1721	}
	1722	pending.condition.wait(io, &q.mutex) catch \|err\| switch (err) {
	1723	error.Canceled => if (pending.remaining.len == elements.len) {
	1724	// Canceled while waiting, and appended no elements.
	1725	return error.Canceled;
	1726	} else {
	1727	// Canceled while waiting, but appended some elements, so report those first.
	1728	io.recancel();
	1729	return elements.len - pending.remaining.len;
	1730	},
	1731	};
	1732	}
	1733	if (pending.remaining.len == elements.len) {
	1734	// The queue was closed while we were waiting. We appended no elements.
	1735	assert(q.closed);
	1736	return error.Closed;
	1737	}
	1738	return elements.len - pending.remaining.len;
1677	1739	}
1678	1740
1679		pub fn get(q: *@This(), io: Io, buffer: []u8, min: usize) Cancelable!usize {
	1741	pub fn get(q: *TypeErasedQueue, io: Io, buffer: []u8, min: usize) (QueueClosedError \|\| Cancelable)!usize {
1680	1742	assert(buffer.len >= min);
1681	1743	if (buffer.len == 0) return 0;
1682	1744	try q.mutex.lock(io);
...	...	@@ -1687,13 +1749,14 @@ pub const TypeErasedQueue = struct {
1687	1749	/// Same as `get`, except does not introduce a cancelation point.
1688	1750	///
1689	1751	/// For a description of cancelation and cancelation points, see `Future.cancel`.
1690		pub fn getUncancelable(q: *TypeErasedQueue, io: Io, buffer: []u8, min: usize) usize {
	1752	pub fn getUncancelable(q: *TypeErasedQueue, io: Io, buffer: []u8, min: usize) QueueClosedError!usize {
1691	1753	assert(buffer.len >= min);
1692	1754	if (buffer.len == 0) return 0;
1693	1755	q.mutex.lockUncancelable(io);
1694	1756	defer q.mutex.unlock(io);
1695	1757	return q.getLocked(io, buffer, min, true) catch \|err\| switch (err) {
1696	1758	error.Canceled => unreachable,
	1759	error.Closed => \|e\| return e,
1697	1760	};
1698	1761	}
1699	1762
...	...	@@ -1703,21 +1766,23 @@ pub const TypeErasedQueue = struct {
1703	1766	return if (slice.len > 0) slice else null;
1704	1767	}
1705	1768
1706		fn getLocked(q: *@This(), io: Io, buffer: []u8, min: usize, uncancelable: bool) Cancelable!usize {
	1769	fn getLocked(q: *TypeErasedQueue, io: Io, buffer: []u8, target: usize, uncancelable: bool) (QueueClosedError \|\| Cancelable)!usize {
1707	1770	// The ring buffer gets first priority, then data should come from any
1708	1771	// queued putters, then finally the ring buffer should be filled with
1709	1772	// data from putters so they can be resumed.
1710	1773
1711		var remaining = buffer;
	1774	// The number of elements we received immediately, before possibly blocking.
	1775	var n: usize = 0;
	1776
1712	1777	while (q.gettableSlice()) \|slice\| {
1713		const copy_len = @min(slice.len, remaining.len);
	1778	const copy_len = @min(slice.len, buffer.len - n);
1714	1779	assert(copy_len > 0);
1715		@memcpy(remaining[0..copy_len], slice[0..copy_len]);
	1780	@memcpy(buffer[n..][0..copy_len], slice[0..copy_len]);
1716	1781	q.start += copy_len;
1717	1782	if (q.buffer.len - q.start == 0) q.start = 0;
1718	1783	q.len -= copy_len;
1719		remaining = remaining[copy_len..];
1720		if (remaining.len == 0) {
	1784	n += copy_len;
	1785	if (n == buffer.len) {
1721	1786	q.fillRingBufferFromPutters(io);
1722	1787	return buffer.len;
1723	1788	}
...	...	@@ -1726,33 +1791,64 @@ pub const TypeErasedQueue = struct {
1726	1791	// Copy directly from putters into buffer.
1727	1792	while (q.putters.popFirst()) \|putter_node\| {
1728	1793	const putter: *Put = @alignCast(@fieldParentPtr("node", putter_node));
1729		const copy_len = @min(putter.remaining.len, remaining.len);
	1794	const copy_len = @min(putter.remaining.len, buffer.len - n);
1730	1795	assert(copy_len > 0);
1731		@memcpy(remaining[0..copy_len], putter.remaining[0..copy_len]);
	1796	@memcpy(buffer[n..][0..copy_len], putter.remaining[0..copy_len]);
1732	1797	putter.remaining = putter.remaining[copy_len..];
1733		remaining = remaining[copy_len..];
1734		if (putter.remaining.len == 0) {
	1798	putter.needed -\|= copy_len;
	1799	n += copy_len;
	1800	if (putter.needed == 0) {
1735	1801	putter.condition.signal(io);
1736		if (remaining.len > 0) continue;
1737		} else q.putters.prepend(putter_node);
1738		assert(remaining.len == 0);
1739		q.fillRingBufferFromPutters(io);
1740		return buffer.len;
	1802	} else {
	1803	assert(n == buffer.len); // we didn't have enough space for the putter
	1804	q.putters.prepend(putter_node);
	1805	}
	1806	if (n == buffer.len) {
	1807	q.fillRingBufferFromPutters(io);
	1808	return buffer.len;
	1809	}
1741	1810	}
1742	1811
1743		// Both ring buffer and putters queue is empty.
1744		const total_filled = buffer.len - remaining.len;
1745		if (total_filled >= min) return total_filled;
	1812	// No need to call `fillRingBufferFromPutters` from this point onwards,
	1813	// because we emptied the ring buffer and the putter queue!
1746	1814
1747		var pending: Get = .{ .remaining = remaining, .condition = .{}, .node = .{} };
	1815	// Don't block if we hit the target or if the queue is closed. Return how
	1816	// many elements we could get immediately, unless the queue was closed and
	1817	// empty, in which case report `error.Closed`.
	1818	if (n == 0 and q.closed) return error.Closed;
	1819	if (n >= target or q.closed) return n;
	1820
	1821	var pending: Get = .{
	1822	.remaining = buffer[n..],
	1823	.needed = target - n,
	1824	.condition = .init,
	1825	.node = .{},
	1826	};
1748	1827	q.getters.append(&pending.node);
1749		defer if (pending.remaining.len > 0) q.getters.remove(&pending.node);
1750		while (pending.remaining.len > 0) if (uncancelable)
1751		pending.condition.waitUncancelable(io, &q.mutex)
1752		else
1753		try pending.condition.wait(io, &q.mutex);
1754		q.fillRingBufferFromPutters(io);
1755		return buffer.len;
	1828	defer if (pending.needed > 0) q.getters.remove(&pending.node);
	1829
	1830	while (pending.needed > 0 and !q.closed) {
	1831	if (uncancelable) {
	1832	pending.condition.waitUncancelable(io, &q.mutex);
	1833	continue;
	1834	}
	1835	pending.condition.wait(io, &q.mutex) catch \|err\| switch (err) {
	1836	error.Canceled => if (pending.remaining.len == buffer.len) {
	1837	// Canceled while waiting, and received no elements.
	1838	return error.Canceled;
	1839	} else {
	1840	// Canceled while waiting, but received some elements, so report those first.
	1841	io.recancel();
	1842	return buffer.len - pending.remaining.len;
	1843	},
	1844	};
	1845	}
	1846	if (pending.remaining.len == buffer.len) {
	1847	// The queue was closed while we were waiting. We received no elements.
	1848	assert(q.closed);
	1849	return error.Closed;
	1850	}
	1851	return buffer.len - pending.remaining.len;
1756	1852	}
1757	1853
1758	1854	/// Called when there is nonzero space available in the ring buffer and
...	...	@@ -1768,7 +1864,8 @@ pub const TypeErasedQueue = struct {
1768	1864	@memcpy(slice[0..copy_len], putter.remaining[0..copy_len]);
1769	1865	q.len += copy_len;
1770	1866	putter.remaining = putter.remaining[copy_len..];
1771		if (putter.remaining.len == 0) {
	1867	putter.needed -\|= copy_len;
	1868	if (putter.needed == 0) {
1772	1869	putter.condition.signal(io);
1773	1870	break;
1774	1871	}
...	...	@@ -1791,59 +1888,101 @@ pub fn Queue(Elem: type) type {
1791	1888	return .{ .type_erased = .init(@ptrCast(buffer)) };
1792	1889	}
1793	1890
1794		/// Appends elements to the end of the queue. The function returns when
1795		/// at least `min` elements have been added to the buffer or sent
1796		/// directly to a consumer.
	1891	pub fn close(q: *@This(), io: Io) void {
	1892	q.type_erased.close(io);
	1893	}
	1894
	1895	/// Appends elements to the end of the queue, potentially blocking if
	1896	/// there is insufficient capacity. Returns when any one of the
	1897	/// following conditions is satisfied:
	1898	///
	1899	/// * At least `target` elements have been added to the queue
	1900	/// * The queue is closed
	1901	/// * The current task is canceled
	1902	///
	1903	/// Returns how many of `elements` have been added to the queue, if any.
	1904	/// If an error is returned, no elements have been added.
1797	1905	///
1798		/// Returns how many elements have been added to the queue.
	1906	/// If the queue is closed or the task is canceled, but some items were
	1907	/// already added before the closure or cancelation, then `put` may
	1908	/// return a number lower than `target`, in which case future calls are
	1909	/// guaranteed to return `error.Canceled` or `error.Closed`.
1799	1910	///
1800		/// Asserts that `elements.len >= min`.
1801		pub fn put(q: *@This(), io: Io, elements: []const Elem, min: usize) Cancelable!usize {
1802		return @divExact(try q.type_erased.put(io, @ptrCast(elements), min * @sizeOf(Elem)), @sizeOf(Elem));
	1911	/// A return value of 0 is only possible if `target` is 0, in which case
	1912	/// the call is guaranteed to queue as many of `elements` as is possible
	1913	/// without blocking.
	1914	///
	1915	/// Asserts that `elements.len >= target`.
	1916	pub fn put(q: *@This(), io: Io, elements: []const Elem, target: usize) (QueueClosedError \|\| Cancelable)!usize {
	1917	return @divExact(try q.type_erased.put(io, @ptrCast(elements), target * @sizeOf(Elem)), @sizeOf(Elem));
1803	1918	}
1804	1919
1805	1920	/// Same as `put` but blocks until all elements have been added to the queue.
1806		pub fn putAll(q: *@This(), io: Io, elements: []const Elem) Cancelable!void {
1807		assert(try q.put(io, elements, elements.len) == elements.len);
	1921	///
	1922	/// If the queue is closed or canceled, `error.Closed` or `error.Canceled`
	1923	/// is returned, and it is unspecified how many, if any, of `elements` were
	1924	/// added to the queue prior to cancelation or closure.
	1925	pub fn putAll(q: *@This(), io: Io, elements: []const Elem) (QueueClosedError \|\| Cancelable)!void {
	1926	const n = try q.put(io, elements, elements.len);
	1927	if (n != elements.len) {
	1928	_ = try q.put(io, elements[n..], elements.len - n);
	1929	unreachable; // partial `put` implies queue was closed or we were canceled
	1930	}
1808	1931	}
1809	1932
1810	1933	/// Same as `put`, except does not introduce a cancelation point.
1811	1934	///
1812	1935	/// For a description of cancelation and cancelation points, see `Future.cancel`.
1813		pub fn putUncancelable(q: *@This(), io: Io, elements: []const Elem, min: usize) usize {
1814		return @divExact(q.type_erased.putUncancelable(io, @ptrCast(elements), min * @sizeOf(Elem)), @sizeOf(Elem));
	1936	pub fn putUncancelable(q: *@This(), io: Io, elements: []const Elem, min: usize) QueueClosedError!usize {
	1937	return @divExact(try q.type_erased.putUncancelable(io, @ptrCast(elements), min * @sizeOf(Elem)), @sizeOf(Elem));
1815	1938	}
1816	1939
1817		pub fn putOne(q: *@This(), io: Io, item: Elem) Cancelable!void {
	1940	/// Appends `item` to the end of the queue, blocking if the queue is full.
	1941	pub fn putOne(q: *@This(), io: Io, item: Elem) (QueueClosedError \|\| Cancelable)!void {
1818	1942	assert(try q.put(io, &.{item}, 1) == 1);
1819	1943	}
1820	1944
1821	1945	/// Same as `putOne`, except does not introduce a cancelation point.
1822	1946	///
1823	1947	/// For a description of cancelation and cancelation points, see `Future.cancel`.
1824		pub fn putOneUncancelable(q: *@This(), io: Io, item: Elem) void {
1825		assert(q.putUncancelable(io, &.{item}, 1) == 1);
	1948	pub fn putOneUncancelable(q: *@This(), io: Io, item: Elem) QueueClosedError!void {
	1949	assert(try q.putUncancelable(io, &.{item}, 1) == 1);
1826	1950	}
1827	1951
1828		/// Receives elements from the beginning of the queue. The function
1829		/// returns when at least `min` elements have been populated inside
1830		/// `buffer`.
	1952	/// Receives elements from the beginning of the queue, potentially blocking
	1953	/// if there are insufficient elements currently in the queue. Returns when
	1954	/// any one of the following conditions is satisfied:
	1955	///
	1956	/// * At least `target` elements have been received from the queue
	1957	/// * The queue is closed and contains no buffered elements
	1958	/// * The current task is canceled
	1959	///
	1960	/// Returns how many elements of `buffer` have been populated, if any.
	1961	/// If an error is returned, no elements have been populated.
	1962	///
	1963	/// If the queue is closed or the task is canceled, but some items were
	1964	/// already received before the closure or cancelation, then `get` may
	1965	/// return a number lower than `target`, in which case future calls are
	1966	/// guaranteed to return `error.Canceled` or `error.Closed`.
1831	1967	///
1832		/// Returns how many elements of `buffer` have been populated.
	1968	/// A return value of 0 is only possible if `target` is 0, in which case
	1969	/// the call is guaranteed to fill as much of `buffer` as is possible
	1970	/// without blocking.
1833	1971	///
1834		/// Asserts that `buffer.len >= min`.
1835		pub fn get(q: *@This(), io: Io, buffer: []Elem, min: usize) Cancelable!usize {
1836		return @divExact(try q.type_erased.get(io, @ptrCast(buffer), min * @sizeOf(Elem)), @sizeOf(Elem));
	1972	/// Asserts that `buffer.len >= target`.
	1973	pub fn get(q: *@This(), io: Io, buffer: []Elem, target: usize) (QueueClosedError \|\| Cancelable)!usize {
	1974	return @divExact(try q.type_erased.get(io, @ptrCast(buffer), target * @sizeOf(Elem)), @sizeOf(Elem));
1837	1975	}
1838	1976
1839	1977	/// Same as `get`, except does not introduce a cancelation point.
1840	1978	///
1841	1979	/// For a description of cancelation and cancelation points, see `Future.cancel`.
1842		pub fn getUncancelable(q: *@This(), io: Io, buffer: []Elem, min: usize) usize {
	1980	pub fn getUncancelable(q: *@This(), io: Io, buffer: []Elem, min: usize) QueueClosedError!usize {
1843	1981	return @divExact(try q.type_erased.getUncancelable(io, @ptrCast(buffer), min * @sizeOf(Elem)), @sizeOf(Elem));
1844	1982	}
1845	1983
1846		pub fn getOne(q: *@This(), io: Io) Cancelable!Elem {
	1984	/// Receives one element from the beginning of the queue, blocking if the queue is empty.
	1985	pub fn getOne(q: *@This(), io: Io) (QueueClosedError \|\| Cancelable)!Elem {
1847	1986	var buf: [1]Elem = undefined;
1848	1987	assert(try q.get(io, &buf, 1) == 1);
1849	1988	return buf[0];
...	...	@@ -1852,9 +1991,9 @@ pub fn Queue(Elem: type) type {
1852	1991	/// Same as `getOne`, except does not introduce a cancelation point.
1853	1992	///
1854	1993	/// For a description of cancelation and cancelation points, see `Future.cancel`.
1855		pub fn getOneUncancelable(q: *@This(), io: Io) Elem {
	1994	pub fn getOneUncancelable(q: *@This(), io: Io) QueueClosedError!Elem {
1856	1995	var buf: [1]Elem = undefined;
1857		assert(q.getUncancelable(io, &buf, 1) == 1);
	1996	assert(try q.getUncancelable(io, &buf, 1) == 1);
1858	1997	return buf[0];
1859	1998	}
1860	1999

lib/std/Io/Threaded.zig+19-14

...	...	@@ -5795,11 +5795,13 @@ fn netLookup(
5795	5795	host_name: HostName,
5796	5796	resolved: *Io.Queue(HostName.LookupResult),
5797	5797	options: HostName.LookupOptions,
5798		) void {
	5798	) net.HostName.LookupError!void {
5799	5799	const t: *Threaded = @ptrCast(@alignCast(userdata));
5800		const current_thread = Thread.getCurrent(t);
5801		const t_io = io(t);
5802		resolved.putOneUncancelable(t_io, .{ .end = netLookupFallible(t, current_thread, host_name, resolved, options) });
	5800	defer resolved.close(io(t));
	5801	netLookupFallible(t, host_name, resolved, options) catch \|err\| switch (err) {
	5802	error.Closed => unreachable, // `resolved` must not be closed until `netLookup` returns
	5803	else => \|e\| return e,
	5804	};
5803	5805	}
5804	5806
5805	5807	fn netLookupUnavailable(
...	...	@@ -5807,22 +5809,23 @@ fn netLookupUnavailable(
5807	5809	host_name: HostName,
5808	5810	resolved: *Io.Queue(HostName.LookupResult),
5809	5811	options: HostName.LookupOptions,
5810		) void {
	5812	) net.HostName.LookupError!void {
5811	5813	_ = host_name;
5812	5814	_ = options;
5813	5815	const t: *Threaded = @ptrCast(@alignCast(userdata));
5814		const t_io = ioBasic(t);
5815		resolved.putOneUncancelable(t_io, .{ .end = error.NetworkDown });
	5816	resolved.close(ioBasic(t));
	5817	return error.NetworkDown;
5816	5818	}
5817	5819
5818	5820	fn netLookupFallible(
5819	5821	t: *Threaded,
5820		current_thread: *Thread,
5821	5822	host_name: HostName,
5822	5823	resolved: *Io.Queue(HostName.LookupResult),
5823	5824	options: HostName.LookupOptions,
5824		) !void {
	5825	) (net.HostName.LookupError \|\| Io.QueueClosedError)!void {
5825	5826	if (!have_networking) return error.NetworkDown;
	5827
	5828	const current_thread: *Thread = .getCurrent(t);
5826	5829	const t_io = io(t);
5827	5830	const name = host_name.bytes;
5828	5831	assert(name.len <= HostName.max_len);
...	...	@@ -6363,7 +6366,7 @@ fn lookupDnsSearch(
6363	6366	host_name: HostName,
6364	6367	resolved: *Io.Queue(HostName.LookupResult),
6365	6368	options: HostName.LookupOptions,
6366		) HostName.LookupError!void {
	6369	) (HostName.LookupError \|\| Io.QueueClosedError)!void {
6367	6370	const t_io = io(t);
6368	6371	const rc = HostName.ResolvConf.init(t_io) catch return error.ResolvConfParseFailed;
6369	6372
...	...	@@ -6407,7 +6410,7 @@ fn lookupDns(
6407	6410	rc: *const HostName.ResolvConf,
6408	6411	resolved: *Io.Queue(HostName.LookupResult),
6409	6412	options: HostName.LookupOptions,
6410		) HostName.LookupError!void {
	6413	) (HostName.LookupError \|\| Io.QueueClosedError)!void {
6411	6414	const t_io = io(t);
6412	6415	const family_records: [2]struct { af: IpAddress.Family, rr: HostName.DnsRecord } = .{
6413	6416	.{ .af = .ip6, .rr = .A },
...	...	@@ -6621,8 +6624,10 @@ fn lookupHosts(
6621	6624	return error.DetectingNetworkConfigurationFailed;
6622	6625	},
6623	6626	},
6624		error.Canceled => \|e\| return e,
6625		error.UnknownHostName => \|e\| return e,
	6627	error.Canceled,
	6628	error.Closed,
	6629	error.UnknownHostName,
	6630	=> \|e\| return e,
6626	6631	};
6627	6632	}
6628	6633
...	...	@@ -6632,7 +6637,7 @@ fn lookupHostsReader(
6632	6637	resolved: *Io.Queue(HostName.LookupResult),
6633	6638	options: HostName.LookupOptions,
6634	6639	reader: *Io.Reader,
6635		) error{ ReadFailed, Canceled, UnknownHostName }!void {
	6640	) error{ ReadFailed, Canceled, UnknownHostName, Closed }!void {
6636	6641	const t_io = io(t);
6637	6642	var addresses_len: usize = 0;
6638	6643	var canonical_name: ?HostName = null;

lib/std/Io/net/HostName.zig+63-44

...	...	@@ -82,19 +82,22 @@ pub const LookupError = error{
82	82	pub const LookupResult = union(enum) {
83	83	address: IpAddress,
84	84	canonical_name: HostName,
85		end: LookupError!void,
86	85	};
87	86
88		/// Adds any number of `IpAddress` into resolved, exactly one canonical_name,
89		/// and then always finishes by adding one `LookupResult.end` entry.
	87	/// Adds any number of `LookupResult.address` into `resolved`, and exactly one
	88	/// `LookupResult.canonical_name`.
90	89	///
91	90	/// Guaranteed not to block if provided queue has capacity at least 16.
	91	///
	92	/// Closes `resolved` before return, even on error.
	93	///
	94	/// Asserts `resolved` is not closed until this call returns.
92	95	pub fn lookup(
93	96	host_name: HostName,
94	97	io: Io,
95	98	resolved: *Io.Queue(LookupResult),
96	99	options: LookupOptions,
97		) void {
	100	) LookupError!void {
98	101	return io.vtable.netLookup(io.userdata, host_name, resolved, options);
99	102	}
100	103
...	...	@@ -211,23 +214,25 @@ pub fn connect(
211	214	port: u16,
212	215	options: IpAddress.ConnectOptions,
213	216	) ConnectError!Stream {
214		var connect_many_buffer: [32]ConnectManyResult = undefined;
215		var connect_many_queue: Io.Queue(ConnectManyResult) = .init(&connect_many_buffer);
	217	var connect_many_buffer: [32]IpAddress.ConnectError!Stream = undefined;
	218	var connect_many_queue: Io.Queue(IpAddress.ConnectError!Stream) = .init(&connect_many_buffer);
216	219
217	220	var connect_many = io.async(connectMany, .{ host_name, io, port, &connect_many_queue, options });
218		var saw_end = false;
219	221	defer {
220		connect_many.cancel(io);
221		if (!saw_end) while (true) switch (connect_many_queue.getOneUncancelable(io)) {
222		.connection => \|loser\| if (loser) \|s\| s.close(io) else \|_\| continue,
223		.end => break,
224		};
	222	connect_many.cancel(io) catch {};
	223	while (connect_many_queue.getOneUncancelable(io)) \|loser\| {
	224	if (loser) \|s\| s.close(io) else \|_\| {}
	225	} else \|err\| switch (err) {
	226	error.Closed => {},
	227	}
225	228	}
226	229
227		var aggregate_error: ConnectError = error.UnknownHostName;
	230	var ip_connect_error: ?IpAddress.ConnectError = null;
228	231
229		while (connect_many_queue.getOne(io)) \|result\| switch (result) {
230		.connection => \|connection\| if (connection) \|stream\| return stream else \|err\| switch (err) {
	232	while (connect_many_queue.getOne(io)) \|result\| {
	233	if (result) \|stream\| {
	234	return stream;
	235	} else \|err\| switch (err) {
231	236	error.SystemResources,
232	237	error.OptionUnsupported,
233	238	error.ProcessFdQuotaExceeded,
...	...	@@ -237,66 +242,80 @@ pub fn connect(
237	242
238	243	error.WouldBlock => return error.Unexpected,
239	244
240		else => \|e\| aggregate_error = e,
241		},
242		.end => \|end\| {
243		saw_end = true;
244		try end;
245		return aggregate_error;
246		},
	245	else => \|e\| ip_connect_error = e,
	246	}
247	247	} else \|err\| switch (err) {
248	248	error.Canceled => \|e\| return e,
	249	error.Closed => {
	250	// There was no successful connection attempt. If there was a lookup error, return that.
	251	try connect_many.await(io);
	252	// Otherwise, return the error from a failed IP connection attempt.
	253	return ip_connect_error orelse
	254	return error.UnknownHostName;
	255	},
249	256	}
250	257	}
251	258
252		pub const ConnectManyResult = union(enum) {
253		connection: IpAddress.ConnectError!Stream,
254		end: ConnectError!void,
255		};
256
257	259	/// Asynchronously establishes a connection to all IP addresses associated with
258	260	/// a host name, adding them to a results queue upon completion.
	261	///
	262	/// Closes `results` before return, even on error.
	263	///
	264	/// Asserts `results` is not closed until this call returns.
259	265	pub fn connectMany(
260	266	host_name: HostName,
261	267	io: Io,
262	268	port: u16,
263		results: *Io.Queue(ConnectManyResult),
	269	results: *Io.Queue(IpAddress.ConnectError!Stream),
264	270	options: IpAddress.ConnectOptions,
265		) void {
	271	) LookupError!void {
	272	defer results.close(io);
	273
266	274	var canonical_name_buffer: [max_len]u8 = undefined;
267	275	var lookup_buffer: [32]HostName.LookupResult = undefined;
268	276	var lookup_queue: Io.Queue(LookupResult) = .init(&lookup_buffer);
269		var group: Io.Group = .init;
270		defer group.cancel(io);
271
272		group.async(io, lookup, .{ host_name, io, &lookup_queue, .{
	277	var lookup_future = io.async(lookup, .{ host_name, io, &lookup_queue, .{
273	278	.port = port,
274	279	.canonical_name_buffer = &canonical_name_buffer,
275	280	} });
	281	defer lookup_future.cancel(io) catch {};
	282
	283	var group: Io.Group = .init;
	284	defer group.cancel(io);
276	285
277	286	while (lookup_queue.getOne(io)) \|dns_result\| switch (dns_result) {
278	287	.address => \|address\| group.async(io, enqueueConnection, .{ address, io, results, options }),
279	288	.canonical_name => continue,
280		.end => \|lookup_result\| {
281		group.wait(io);
282		results.putOneUncancelable(io, .{ .end = lookup_result });
283		return;
284		},
285	289	} else \|err\| switch (err) {
286		error.Canceled => \|e\| {
287		group.cancel(io);
288		results.putOneUncancelable(io, .{ .end = e });
	290	error.Canceled => \|e\| return e,
	291	error.Closed => {
	292	group.wait(io);
	293	return lookup_future.await(io);
289	294	},
290	295	}
291	296	}
292
293	297	fn enqueueConnection(
294	298	address: IpAddress,
295	299	io: Io,
296		queue: *Io.Queue(ConnectManyResult),
	300	queue: *Io.Queue(IpAddress.ConnectError!Stream),
297	301	options: IpAddress.ConnectOptions,
298	302	) void {
299		queue.putOneUncancelable(io, .{ .connection = address.connect(io, options) });
	303	enqueueConnectionFallible(address, io, queue, options) catch \|err\| switch (err) {
	304	error.Canceled => {},
	305	};
	306	}
	307	fn enqueueConnectionFallible(
	308	address: IpAddress,
	309	io: Io,
	310	queue: *Io.Queue(IpAddress.ConnectError!Stream),
	311	options: IpAddress.ConnectOptions,
	312	) Io.Cancelable!void {
	313	const result = address.connect(io, options);
	314	errdefer if (result) \|s\| s.close(io) else \|_\| {};
	315	queue.putOne(io, result) catch \|err\| switch (err) {
	316	error.Closed => unreachable, // `queue` must not be closed
	317	error.Canceled => \|e\| return e,
	318	};
300	319	}
301	320
302	321	pub const ResolvConf = struct {

lib/std/Io/net/test.zig+14-16

...	...	@@ -129,7 +129,7 @@ test "resolve DNS" {
129	129	var results_buffer: [32]net.HostName.LookupResult = undefined;
130	130	var results: Io.Queue(net.HostName.LookupResult) = .init(&results_buffer);
131	131
132		net.HostName.lookup(try .init("localhost"), io, &results, .{
	132	try net.HostName.lookup(try .init("localhost"), io, &results, .{
133	133	.port = 80,
134	134	.canonical_name_buffer = &canonical_name_buffer,
135	135	});
...	...	@@ -142,11 +142,10 @@ test "resolve DNS" {
142	142	addresses_found += 1;
143	143	},
144	144	.canonical_name => \|canonical_name\| try testing.expectEqualStrings("localhost", canonical_name.bytes),
145		.end => \|end\| {
146		try end;
147		break;
148		},
149		} else \|err\| return err;
	145	} else \|err\| switch (err) {
	146	error.Closed => {},
	147	error.Canceled => \|e\| return e,
	148	}
150	149
151	150	try testing.expect(addresses_found != 0);
152	151	}
...	...	@@ -161,20 +160,19 @@ test "resolve DNS" {
161	160	net.HostName.lookup(try .init("example.com"), io, &results, .{
162	161	.port = 80,
163	162	.canonical_name_buffer = &canonical_name_buffer,
164		});
	163	}) catch \|err\| switch (err) {
	164	error.UnknownHostName => return error.SkipZigTest,
	165	error.NameServerFailure => return error.SkipZigTest,
	166	else => \|e\| return e,
	167	};
165	168
166	169	while (results.getOne(io)) \|result\| switch (result) {
167	170	.address => {},
168	171	.canonical_name => {},
169		.end => \|end\| {
170		end catch \|err\| switch (err) {
171		error.UnknownHostName => return error.SkipZigTest,
172		error.NameServerFailure => return error.SkipZigTest,
173		else => return err,
174		};
175		break;
176		},
177		} else \|err\| return err;
	172	} else \|err\| switch (err) {
	173	error.Closed => {},
	174	error.Canceled => \|e\| return e,
	175	}
178	176	}
179	177	}
180	178

lib/std/Io/test.zig+53-8

...	...	@@ -209,10 +209,10 @@ test "select" {
209	209	return;
210	210	},
211	211	};
212		defer if (get_a.cancel(io)) \|_\| {} else \|_\| @panic("fail");
	212	defer _ = get_a.cancel(io) catch {};
213	213
214	214	var get_b = try io.concurrent(Io.Queue(u8).getOne, .{ &queue, io });
215		defer if (get_b.cancel(io)) \|_\| {} else \|_\| @panic("fail");
	215	defer _ = get_b.cancel(io) catch {};
216	216
217	217	var timeout = io.async(Io.sleep, .{ io, .fromMilliseconds(1), .awake });
218	218	defer timeout.cancel(io) catch {};
...	...	@@ -225,12 +225,9 @@ test "select" {
225	225	.get_a => return error.TestFailure,
226	226	.get_b => return error.TestFailure,
227	227	.timeout => {
228		// Unblock the queues to avoid making this unit test depend on
229		// cancellation.
230		queue.putOneUncancelable(io, 1);
231		queue.putOneUncancelable(io, 1);
232		try testing.expectEqual(1, try get_a.await(io));
233		try testing.expectEqual(1, try get_b.await(io));
	228	queue.close(io);
	229	try testing.expectError(error.Closed, get_a.await(io));
	230	try testing.expectError(error.Closed, get_b.await(io));
234	231	},
235	232	}
236	233	}
...	...	@@ -256,6 +253,54 @@ test "Queue" {
256	253	try testQueue(5);
257	254	}
258	255
	256	test "Queue.close single-threaded" {
	257	const io = std.testing.io;
	258
	259	var buf: [10]u8 = undefined;
	260	var queue: Io.Queue(u8) = .init(&buf);
	261
	262	try queue.putAll(io, &.{ 0, 1, 2, 3, 4, 5, 6 });
	263	try expectEqual(3, try queue.put(io, &.{ 7, 8, 9, 10 }, 0)); // there is capacity for 3 more items
	264
	265	var get_buf: [4]u8 = undefined;
	266
	267	// Receive some elements before closing
	268	try expectEqual(4, try queue.get(io, &get_buf, 0));
	269	try expectEqual(0, get_buf[0]);
	270	try expectEqual(1, get_buf[1]);
	271	try expectEqual(2, get_buf[2]);
	272	try expectEqual(3, get_buf[3]);
	273	try expectEqual(4, try queue.getOne(io));
	274
	275	// ...and add a couple more now there's space
	276	try queue.putAll(io, &.{ 20, 21 });
	277
	278	queue.close(io);
	279
	280	// Receive more elements after closing
	281	try expectEqual(4, try queue.get(io, &get_buf, 0));
	282	try expectEqual(5, get_buf[0]);
	283	try expectEqual(6, get_buf[1]);
	284	try expectEqual(7, get_buf[2]);
	285	try expectEqual(8, get_buf[3]);
	286	try expectEqual(9, try queue.getOne(io));
	287
	288	// Cannot put anything while closed, even if the buffer has space
	289	try expectError(error.Closed, queue.putOne(io, 100));
	290	try expectError(error.Closed, queue.putAll(io, &.{ 101, 102 }));
	291	try expectError(error.Closed, queue.putUncancelable(io, &.{ 103, 104 }, 0));
	292
	293	// Even if we ask for 3 items, the queue is closed, so we only get the last 2
	294	try expectEqual(2, try queue.get(io, &get_buf, 4));
	295	try expectEqual(20, get_buf[0]);
	296	try expectEqual(21, get_buf[1]);
	297
	298	// The queue is now empty, so `get` should return `error.Closed` too
	299	try expectError(error.Closed, queue.getOne(io));
	300	try expectError(error.Closed, queue.get(io, &get_buf, 0));
	301	try expectError(error.Closed, queue.putUncancelable(io, &get_buf, 2));
	302	}
	303
259	304	test "Event" {
260	305	const global = struct {
261	306	fn waitAndRead(io: Io, event: Io.Event, ptr: const u32) Io.Cancelable!u32 {