include/boost/corosio/native/detail/select/select_scheduler.hpp

99.4% Lines (177 / 178, 1 excl) 100.0% Functions (12 / 12)

[ ] prev/next file n p prev/next uncovered line

select_scheduler.hpp

f(x) Functions (12)

Function Calls Lines Blocks

Line	Hits	Source Code
1		//
2		// Copyright (c) 2026 Steve Gerbino
3		// Copyright (c) 2026 Michael Vandeberg
4		//
5		// Distributed under the Boost Software License, Version 1.0. (See accompanying
6		// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7		//
8		// Official repository: https://github.com/cppalliance/corosio
9		//
10
11		#ifndef BOOST_COROSIO_NATIVE_DETAIL_SELECT_SELECT_SCHEDULER_HPP
12		#define BOOST_COROSIO_NATIVE_DETAIL_SELECT_SELECT_SCHEDULER_HPP
13
14		#include <boost/corosio/detail/platform.hpp>
15
16		#if BOOST_COROSIO_HAS_SELECT
17
18		#include <boost/corosio/detail/config.hpp>
19		#include <boost/capy/ex/execution_context.hpp>
20
21		#include <boost/corosio/native/detail/reactor/reactor_scheduler.hpp>
22		#include <boost/corosio/native/detail/reactor/reactor_signal_pipe.hpp>
23
24		#include <boost/corosio/native/detail/select/select_traits.hpp>
25		#include <boost/corosio/detail/timer_service.hpp>
26		#include <boost/corosio/native/detail/make_err.hpp>
27
28		#include <boost/corosio/detail/except.hpp>
29
30		#include <sys/select.h>
31		#include <unistd.h>
32		#include <errno.h>
33		#include <fcntl.h>
34
35		#include <atomic>
36		#include <chrono>
37		#include <cstdint>
38		#include <limits>
39		#include <mutex>
40		#include <new>
41		#include <unordered_map>
42
43		namespace boost::corosio::detail {
44
45		struct select_op;
46
47		/** POSIX scheduler using select() for I/O multiplexing.
48
49		This scheduler implements the scheduler interface using the POSIX select()
50		call for I/O event notification. It inherits the shared reactor threading
51		model from reactor_scheduler: signal state machine, inline completion
52		budget, work counting, and the do_one event loop.
53
54		The design mirrors epoll_scheduler for behavioral consistency:
55		- Same single-reactor thread coordination model
56		- Same deferred I/O pattern (reactor marks ready; workers do I/O)
57		- Same timer integration pattern
58
59		Known Limitations:
60		- FD_SETSIZE (~1024) limits maximum concurrent connections
61		- O(n) scanning: rebuilds fd_sets each iteration
62		- Level-triggered only (no edge-triggered mode)
63
64		@par Thread Safety
65		All public member functions are thread-safe.
66		*/
67		class BOOST_COROSIO_DECL select_scheduler final : public reactor_scheduler
68		{
69		public:
70		/** Construct the scheduler.
71
72		Creates a self-pipe for reactor interruption.
73
74		@param ctx Reference to the owning execution_context.
75		@param concurrency_hint Hint for expected thread count (unused).
76		*/
77		select_scheduler(capy::execution_context& ctx, int concurrency_hint = -1);
78
79		/// Destroy the scheduler.
80		~select_scheduler() override;
81
82		select_scheduler(select_scheduler const&) = delete;
83		select_scheduler& operator=(select_scheduler const&) = delete;
84
85		/// Shut down the scheduler, draining pending operations.
86		void shutdown() override;
87
88		/** Return the maximum file descriptor value supported.
89
90		Returns FD_SETSIZE - 1, the maximum fd value that can be
91		monitored by select(). Operations with fd >= FD_SETSIZE
92		will fail with EINVAL.
93
94		@return The maximum supported file descriptor value.
95		*/
96		static constexpr int max_fd() noexcept
97		{
98		return FD_SETSIZE - 1;
99		}
100
101		/** Register a descriptor for persistent monitoring.
102
103		The fd is added to the registered_descs_ map and will be
104		included in subsequent select() calls. The reactor is
105		interrupted so a blocked select() rebuilds its fd_sets.
106
107		@param fd The file descriptor to register.
108		@param desc Pointer to descriptor state for this fd.
109
110		@return The error if the fd cannot be tracked, otherwise a
111		default constructed error code.
112		*/
113		std::error_code
114		register_descriptor(int fd, reactor_descriptor_state* desc) const;
115
116		/// No-op: write readiness is watched from registration on.
117		std::error_code
118	2709x	ensure_write_registered(int, reactor_descriptor_state*) const noexcept
119		{
120	2709x	return {};
121		}
122
123		/** Deregister a persistently registered descriptor.
124
125		@param fd The file descriptor to deregister.
126		*/
127		void deregister_descriptor(int fd) const;
128
129		/** Interrupt the reactor so it rebuilds its fd_sets.
130
131		Called when a write, connect, or write-wait op is registered
132		after the reactor's snapshot was taken. Without this,
133		select() may block not watching for writability on the fd.
134		*/
135		void notify_reactor() const;
136
137		/// Watch the read end of the POSIX signal self-pipe (see scheduler.hpp).
138	273x	[[nodiscard]] std::error_code register_signal_reader(int read_fd) override
139		{
140	273x	return register_descriptor(read_fd, signal_pipe_reader_.arm());
141		}
142
143		private:
144		void run_task(lock_type& lock, context_type& ctx, long timeout_us) override;
145		void interrupt_reactor() const override;
146
147		/// Rebuild the poll set a blocked select() was given.
148	467x	void notify_reparked() const override
149		{
150	467x	interrupt_reactor();
151	467x	}
152		long calculate_timeout(long requested_timeout_us) const;
153
154		// Watches the global signal self-pipe's read end (armed lazily by
155		// register_signal_reader on the first signal registration).
156		reactor_signal_pipe_reader signal_pipe_reader_;
157
158		// Self-pipe for interrupting select()
159		int pipe_fds_[2]; // [0]=read, [1]=write
160
161		// Per-fd tracking for fd_set building
162		mutable std::unordered_map<int, reactor_descriptor_state*>
163		registered_descs_;
164		mutable int max_fd_ = -1;
165		};
166
167	1958x	inline select_scheduler::select_scheduler(capy::execution_context&, int)
168	1958x	: pipe_fds_{-1, -1}
169	1958x	, max_fd_(-1)
170		{
171	1958x	if (::pipe(pipe_fds_) < 0)
172	1x	detail::throw_system_error(make_err(errno), "pipe");
173
174	5862x	for (int i = 0; i < 2; ++i)
175		{
176	3911x	int flags = ::fcntl(pipe_fds_[i], F_GETFL, 0);
177	3911x	if (flags == -1)
178		{
179	2x	int errn = errno;
180	2x	::close(pipe_fds_[0]);
181	2x	::close(pipe_fds_[1]);
182	2x	detail::throw_system_error(make_err(errn), "fcntl F_GETFL");
183		}
184	3909x	if (::fcntl(pipe_fds_[i], F_SETFL, flags \| O_NONBLOCK) == -1)
185		{
186	2x	int errn = errno;
187	2x	::close(pipe_fds_[0]);
188	2x	::close(pipe_fds_[1]);
189	2x	detail::throw_system_error(make_err(errn), "fcntl F_SETFL");
190		}
191	3907x	if (::fcntl(pipe_fds_[i], F_SETFD, FD_CLOEXEC) == -1)
192		{
193	2x	int errn = errno;
194	2x	::close(pipe_fds_[0]);
195	2x	::close(pipe_fds_[1]);
196	2x	detail::throw_system_error(make_err(errn), "fcntl F_SETFD");
197		}
198		}
199
200	1951x	completed_ops_.push(&task_op_);
201	1972x	}
202
203	3902x	inline select_scheduler::~select_scheduler()
204		{
205	1951x	if (pipe_fds_[0] >= 0)
206	1951x	::close(pipe_fds_[0]);
207	1951x	if (pipe_fds_[1] >= 0)
208	1951x	::close(pipe_fds_[1]);
209	3902x	}
210
211		inline void
212	1951x	select_scheduler::shutdown()
213		{
214	1951x	shutdown_drain();
215
216	1951x	if (pipe_fds_[1] >= 0)
217	1951x	interrupt_reactor();
218	1951x	}
219
220		inline std::error_code
221	9846x	select_scheduler::register_descriptor(
222		int fd, reactor_descriptor_state* desc) const
223		{
224	9846x	if (fd < 0 \|\| fd >= FD_SETSIZE)
225	1x	return make_err(EMFILE);
226
227		// A completion queued by an earlier registration of the same state
228		// may still be running, so the fields it reads change under its
229		// mutex, and the mutex mode is only written when it differs.
230	9845x	if (desc->mutex.enabled() != reactor_io_locking_)
231	3x	desc->mutex.set_enabled(reactor_io_locking_);
232		{
233	9845x	conditionally_enabled_mutex::scoped_lock lock(desc->mutex);
234	9845x	desc->registered_events = reactor_event_read \| reactor_event_write;
235	9845x	desc->unpollable = false; // the state is reused across adoptions
236	9845x	desc->fd = fd;
237	9845x	desc->scheduler_ = this;
238	9845x	desc->ready_events_.store(0, std::memory_order_release);
239		// object_ref_ is not touched: a queued invocation from an
240		// earlier registration still owns the reference in it.
241	9845x	desc->read_ready = false;
242	9845x	desc->write_ready = false;
243	9845x	}
244
245		{
246	9845x	mutex_type::scoped_lock lock(mutex_);
247		try
248		{
249	9845x	registered_descs_[fd] = desc;
250		}
251	1x	catch (std::bad_alloc const&)
252		{
253	1x	return make_err(ENOMEM);
254	1x	}
255	9844x	if (fd > max_fd_)
256	9363x	max_fd_ = fd;
257	9845x	}
258
259	9844x	interrupt_reactor();
260	9844x	return {};
261		}
262
263		inline void
264	9572x	select_scheduler::deregister_descriptor(int fd) const
265		{
266	9572x	mutex_type::scoped_lock lock(mutex_);
267
268	9572x	auto it = registered_descs_.find(fd);
269	9572x	if (it == registered_descs_.end())
270	✗	return;
271
272	9572x	registered_descs_.erase(it);
273
274	9572x	if (fd == max_fd_)
275		{
276	7658x	max_fd_ = pipe_fds_[0];
277	12714x	for (auto& [registered_fd, state] : registered_descs_)
278		{
279	5056x	if (registered_fd > max_fd_)
280	4823x	max_fd_ = registered_fd;
281		}
282		}
283	9572x	}
284
285		inline void
286	6764x	select_scheduler::notify_reactor() const
287		{
288	6764x	interrupt_reactor();
289	6764x	}
290
291		inline void
292	25515x	select_scheduler::interrupt_reactor() const
293		{
294	25515x	char byte = 1;
295	25515x	[[maybe_unused]] auto r = ::write(pipe_fds_[1], &byte, 1);
296	25515x	}
297
298		inline long
299	17846x	select_scheduler::calculate_timeout(long requested_timeout_us) const
300		{
301	17846x	if (requested_timeout_us == 0)
302	−	return 0; // LCOV_EXCL_LINE run_task passes 0 via task_interrupted_, never through this argument
303
304	17846x	auto* tsvc = timers();
305	17846x	if (!tsvc)
306	11374x	return requested_timeout_us;
307	6472x	auto nearest = tsvc->nearest_expiry();
308	6472x	if (nearest == timer_service::time_point::max())
309	139x	return requested_timeout_us;
310
311	6333x	auto now = std::chrono::steady_clock::now();
312	6333x	if (nearest <= now)
313	155x	return 0;
314
315		auto timer_timeout_us =
316	6178x	std::chrono::duration_cast<std::chrono::microseconds>(nearest - now)
317	6178x	.count();
318
319	6178x	constexpr auto long_max =
320		static_cast<long long>((std::numeric_limits<long>::max)());
321		auto capped_timer_us =
322	6178x	(std::min)((std::max)(static_cast<long long>(timer_timeout_us),
323	6178x	static_cast<long long>(0)),
324	6178x	long_max);
325
326	6178x	if (requested_timeout_us < 0)
327	6172x	return static_cast<long>(capped_timer_us);
328
329		return static_cast<long>(
330	6x	(std::min)(static_cast<long long>(requested_timeout_us),
331	6x	capped_timer_us));
332		}
333
334		inline void
335	144069x	select_scheduler::run_task(lock_type& lock, context_type& ctx, long timeout_us)
336		{
337		long effective_timeout_us =
338	144069x	task_interrupted_ ? 0 : calculate_timeout(timeout_us);
339
340		// Snapshot registered descriptors while holding lock.
341		// Record which directions each fd needs monitored to avoid a hot
342		// loop: select is level-triggered, so a writable socket (nearly
343		// always writable) or an always-readable fd (/dev/zero, a pipe at
344		// EOF) would return select() immediately every iteration if
345		// unconditionally added. Membership in both sets is opt-in: a
346		// parked op or wait in a direction opts that direction in. The
347		// exceptional set is opt-in too, for any parked op or wait:
348		// Darwin reports a character device (/dev/zero, /dev/null) as
349		// exceptional on every call.
350		struct fd_entry
351		{
352		int fd;
353		reactor_descriptor_state* desc;
354		std::uint32_t want;
355		};
356		fd_entry snapshot[FD_SETSIZE];
357	144069x	int snapshot_count = 0;
358
359		// The caller may have released the lock to hand queued work to a
360		// peer, and deregister_descriptor() erases from this map under it.
361	144069x	if (!lock.owns_lock())
362	126220x	lock.lock();
363
364	398341x	for (auto& [fd, desc] : registered_descs_)
365		{
366	254272x	if (snapshot_count < FD_SETSIZE)
367		{
368	254272x	conditionally_enabled_mutex::scoped_lock desc_lock(desc->mutex);
369	254272x	snapshot[snapshot_count].fd = fd;
370	254272x	snapshot[snapshot_count].desc = desc;
371	254272x	snapshot[snapshot_count].want =
372	254272x	((desc->read_op \|\| desc->wait_read_op) ? reactor_event_read
373	254272x	: 0) \|
374	253898x	((desc->write_op \|\| desc->connect_op \|\| desc->wait_write_op)
375	508170x	? reactor_event_write
376	254272x	: 0) \|
377	254272x	(desc->wait_error_op ? reactor_event_error : 0);
378	254272x	++snapshot_count;
379	254272x	}
380		}
381
382	144069x	if (lock.owns_lock())
383	144068x	lock.unlock();
384
385	144069x	task_cleanup on_exit{this, &lock, ctx};
386
387		fd_set read_fds, write_fds, except_fds;
388	2449173x	FD_ZERO(&read_fds);
389	2449173x	FD_ZERO(&write_fds);
390	2449173x	FD_ZERO(&except_fds);
391
392	144069x	FD_SET(pipe_fds_[0], &read_fds);
393	144069x	int nfds = pipe_fds_[0];
394
395	398341x	for (int i = 0; i < snapshot_count; ++i)
396		{
397	254272x	int fd = snapshot[i].fd;
398	254272x	if (snapshot[i].want & reactor_event_read)
399	117409x	FD_SET(fd, &read_fds);
400	254272x	if (snapshot[i].want & reactor_event_write)
401	2973x	FD_SET(fd, &write_fds);
402	254272x	if (snapshot[i].want != 0)
403	120577x	FD_SET(fd, &except_fds);
404	254272x	if (fd > nfds)
405	142229x	nfds = fd;
406		}
407
408		struct timeval tv;
409	144069x	struct timeval* tv_ptr = nullptr;
410	144069x	if (effective_timeout_us >= 0)
411		{
412	133204x	tv.tv_sec = effective_timeout_us / 1000000;
413	133204x	tv.tv_usec = effective_timeout_us % 1000000;
414	133204x	tv_ptr = &tv;
415		}
416
417	144069x	int ready = ::select(nfds + 1, &read_fds, &write_fds, &except_fds, tv_ptr);
418
419		// EINTR: signal interrupted select(), just retry.
420		// EBADF: an fd was closed between snapshot and select(); retry
421		// with a fresh snapshot from registered_descs_.
422		// Both fall through with no ready descriptors rather than
423		// returning: the caller handed this function an owned lock that
424		// only the epilogue below re-acquires.
425	144069x	if (ready < 0)
426		{
427	3x	if (errno != EINTR && errno != EBADF)
428	1x	detail::throw_system_error(make_err(errno), "select");
429	2x	ready = 0;
430		}
431
432		// Process timers outside the lock
433	144068x	if (auto* tsvc = timers())
434	27882x	tsvc->process_expired();
435
436	144068x	ready_queue local_ops;
437
438	144068x	if (ready > 0)
439		{
440	18344x	if (FD_ISSET(pipe_fds_[0], &read_fds))
441		{
442		char buf[256];
443	22660x	while (::read(pipe_fds_[0], buf, sizeof(buf)) > 0)
444		{
445		}
446		}
447
448	105795x	for (int i = 0; i < snapshot_count; ++i)
449		{
450	87451x	int fd = snapshot[i].fd;
451	87451x	reactor_descriptor_state* desc = snapshot[i].desc;
452
453	87451x	std::uint32_t flags = 0;
454	87451x	if (FD_ISSET(fd, &read_fds))
455	9725x	flags \|= reactor_event_read;
456	87451x	if (FD_ISSET(fd, &write_fds))
457	2689x	flags \|= reactor_event_write;
458	87451x	if (FD_ISSET(fd, &except_fds))
459	10x	flags \|= reactor_event_error;
460
461	87451x	if (flags == 0)
462	75035x	continue;
463
464	12416x	desc->add_ready_events(flags);
465
466	12416x	bool expected = false;
467	12416x	if (desc->is_enqueued_.compare_exchange_strong(
468		expected, true, std::memory_order_release,
469		std::memory_order_relaxed))
470		{
471	6215x	local_ops.push(desc);
472		}
473		}
474		}
475
476	144068x	lock.lock();
477
478	144068x	completed_ops_.splice(local_ops);
479	144069x	}
480
481		} // namespace boost::corosio::detail
482
483		#endif // BOOST_COROSIO_HAS_SELECT
484
485		#endif // BOOST_COROSIO_NATIVE_DETAIL_SELECT_SELECT_SCHEDULER_HPP
486