Return to DESCR CVS log

Up to [cvs.NetBSD.org] / pkgsrc / devel / libepoll-shim

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/
        !             4:
        !             5: It may be useful for porting other software that uses epoll as well.
        !             6:
        !             7: The library provides implementation of Linux timerfd_create(2) related
        !             8: APIs, eventfd(2), signalfd(2).
        !             9:
        !            10: However, this library contains some very ugly hacks and workarounds.
        !            11: For example:
        !            12:
        !            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.
        !            21:
        !            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.
        !            26:
        !            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.
        !            35:
        !            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.
        !            43:
        !            44: The following operating systems are supported:
        !            45:
        !            46: FreeBSD >= 11.4, >= 12.2, >= 13.0
        !            47: NetBSD >= 9.1
        !            48: OpenBSD >= 6.7