Product SiteDocumentation Site

Name

tc_wait_fd, tc_wait_fd_prio, tc_register_fd, tc_unregister_fd, tc_rearm, tc_fd — libtcr file descriptor functions

Synopsis

#include <tc/threaded_cr.h>

struct tc_fd *tc_register_fd(int fd);

void tc_unregister_fd(struct tc_fd *tcfd);

enum tc_rv tc_wait_fd(__uint32_t ep_events, struct tc_fd *tcfd);

enum tc_rv tc_wait_fd_prio(__uint32_t ep_events, struct tc_fd *tcfd);

enum tc_rv tc_rearm(struct tc_fd *the_tc_fd);

int tc_fd(struct tc_fd *tcfd);

Description

tc_register_fd() adds a fd to the library's data structures and the epoll-fd. You need to register each fd you want to wait later on. Note: tc_register_fd() sets the O_NONBLOCK flag on the file descriptor.
tc_unregister_fd() removes a file descriptor from the library's data structures and the epoll-fd. Note: This call needs to make sure that all system level threads see that change in an consistent manner, i.e. it synchronizes all system level threads.
tc_wait_fd() waits for events on an registered file descriptor tcfd. ep_events may be EPOLLIN, EPOLLOUT, or any of epoll_ctl(2)'s events.
Note: EPOLLONESHOT gets implicitly added by libtcr. In order to build high performing applications it is quite usual to have multiple tc_threads waiting for a single event with tc_wait_fd(). Only one of all parallel waiting tc_threads will get woken up.
tc_wait_fd_prio() acts like tc_wait_fd(), only that it always takes precedence over all tc_threads waiting in tc_wait_fd(). I.e. If the file descriptor gets ready tc_wait_fd_prio() will return if there is one thread waiting with this function. Only if there is no one waiting with tc_wait_fd_prio() a tc_wait_fd() call will return.
tc_rearm() rearms the events on the file description. If a threads that waited in tc_wait_fd() got woken up, and finished with read/write operations on the file descriptor, with calling tc_rearm() it causes an other tc_thread waiting for that file descriptor to become ready to return from tc_wait_fd().

Return Values

tc_wait_fd() may return
RV_OK
The event you waited for occurred.
RV_INTR
A tc_signal, that is subscribed by this thread, was fired.
RV_FAILED
The file descriptor entered an error state.

Author

Philipp Reisner