Annotation of pkgsrc/devel/libepoll-shim/DESCR, Revision 1.1
1.1 ! jdolecek 1: This is a small library that implements epoll on top of kqueue. It
! 2: has been successfully used to port libinput, libevdev, Wayland and
! 3: more software to FreeBSD: https://www.freshports.org/devel/libepoll-shim/
! 5: It may be useful for porting other software that uses epoll as well.
! 7: The library provides implementation of Linux timerfd_create(2) related
! 8: APIs, eventfd(2), signalfd(2).
! 10: However, this library contains some very ugly hacks and workarounds.
! 11: For example:
! 13: - When using timerfd, signalfd or eventfd, the system calls read,
! 14: write and close are redefined as macros to internal helper
! 15: functions. This is needed as there is some internal context that
! 16: has to be free'd properly. This means that you shouldn't create
! 17: a timerfd/signalfd in one part of a program and close it in a
! 18: different part where sys/timerfd.h isn't included. The context
! 19: would leak. Luckily, software such as libinput behaves very nicely
! 20: and puts all timerfd related code in a single source file.
! 22: - There is limited support for file descriptors that lack support
! 23: for kqueue but are supported by poll(2). This includes graphics
! 24: or sound devices under /dev. Those descriptors are handled in an
! 25: outer poll(2) loop. Edge triggering using EPOLLET will not work.
! 27: - Shimmed file descriptors cannot be shared between processes. On
! 28: fork() those fds are closed. When trying to pass a shimmed fd to
! 29: another process the sendmsg call will return EOPNOTSUPP. In most
! 30: cases sharing epoll/timerfd/signalfd is a bad idea anyway, but
! 31: there are some legitimate use cases (for example sharing semaphore
! 32: eventfds, issue #23). When the OS natively supports eventfds (as
! 33: is the case for FreeBSD >= 13) this library won't provide eventfd
! 34: shims or the sys/eventfd.h header.
! 36: - There is no proper notification mechanism for changes to the
! 37: system CLOCK_REALTIME clock on BSD systems. Also, kevent
! 38: EVFILT_TIMERs use the system monotonic clock as reference.
! 39: Therefore, in order to implement absolute (TFD_TIMER_ABSTIME)
! 40: CLOCK_REALTIME timerfds or cancellation support
! 41: (TFD_TIMER_CANCEL_ON_SET), a thread is spawned that periodically
! 42: polls the system boot time for changes to the realtime clock.
! 44: The following operating systems are supported:
! 46: FreeBSD >= 11.4, >= 12.2, >= 13.0
! 47: NetBSD >= 9.1
! 48: OpenBSD >= 6.7