Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
iv_fd(3)		  ivykis programmer's manual		      iv_fd(3)

NAME
       iv_fd_register, iv_fd_register_try, iv_fd_unregister, iv_fd_registered,
       iv_fd_set_handler_in,  iv_fd_set_handler_err,  iv_fd_set_handler_out  -
       deal with ivykis	file descriptors

SYNOPSIS
       #include	<iv.h>

       struct iv_fd {
	       int	       fd;
	       void	       *cookie;
	       void	       (*handler_in)(void *);
	       void	       (*handler_out)(void *);
	       void	       (*handler_err)(void *);
       };

       void IV_FD_INIT(struct iv_fd *fd);
       void iv_fd_register(struct iv_fd	*fd);
       int iv_fd_register_try(struct iv_fd *fd);
       void iv_fd_unregister(struct iv_fd *fd);
       int iv_fd_registered(const struct iv_fd *fd);
       void iv_fd_set_handler_in(struct	iv_fd *fd, void	(*handler)(void	*));
       void iv_fd_set_handler_out(struct iv_fd *fd, void (*handler)(void *));
       void iv_fd_set_handler_err(struct iv_fd *fd, void (*handler)(void *));

DESCRIPTION
       The  functions  iv_fd_register  and  iv_fd_unregister register, respec-
       tively unregister, a file descriptor with the current  thread's	ivykis
       event loop.  Calling iv_fd_registered on	a file descriptor returns true
       if that file descriptor is currently registered with ivykis.

       When a file descriptor that is registered with ivykis becomes ready for
       input  or output, or an error condition occurs on that file descriptor,
       and a callback function for that	event has been specified,  that	 call-
       back function will be called in the thread that the file	descriptor was
       registered in.

       And conversely, when a file descriptor that is already ready for	 input
       or  output  or  already	has  an	error condition	set is registered with
       ivykis, and the corresponding callback function pointer	is  not	 NULL,
       the  callback function will be called in	the next iteration of the cur-
       rent thread's ivykis event loop.

       Before a	file descriptor	is registered, it must have  been  initialised
       by  calling  IV_FD_INIT	on it, and must	have had its ->fd member field
       set to a	valid OS file descriptor.  The ->handler_in, ->handler_out and
       ->handler_err  member fields point to callback functions	that are to be
       called when the specified file descriptor becomes ready	for  input  or
       output or an error condition occurs.  If	any handler function is	set to
       NULL, it	indicates that the application is not interested in being  no-
       tified of the corresponding event.

       An  application	is  not	allowed	to change the ->fd member while	a file
       descriptor is registered.

       iv_fd_set_handler_in changes the	callback function to  be  called  when
       descriptor  fd  becomes ready for input.	 An application	is not allowed
       to directly change the ->handler_in member after	 the  file  descriptor
       has been	registered, this function has to be used instead.  Conversely,
       it is not allowed to use	this function before the file  descriptor  has
       been registered.

       iv_fd_set_handler_out  is  analogous  to	 iv_fd_set_handler_in, only it
       deals with the callback function	for output readiness (->handler_out).

       iv_fd_set_handler_err  is   analogous   to   iv_fd_set_handler_in   and
       iv_fd_set_handler_out, only it deals with the callback function for er-
       ror conditions (->handler_err).

       When a handler function was NULL, and was set to	a  non-NULL  value  by
       calling	iv_fd_set_handler_in,  iv_fd_set_handler_out or	iv_fd_set_han-
       dler_err, and the file descriptor was already ready for input  or  out-
       put,  or	already	had an error condition set, an event is	generated, and
       the specified callback function will be called in the next iteration of
       the current thread's event loop.	 The application does not need to poll
       the file	descriptor to see if a condition was already raised.

       Callback	functions are passed a cookie value as their  first  and  sole
       argument.  If the application wishes to use this	facility for transfer-
       ring data to the	callback function, it should set the  ->cookie	member
       of a file descriptor to a value of type void *.	This value can be mod-
       ified directly by the application at any	time without calling a	helper
       function.

       When  a	file descriptor	is registered with ivykis, it is transparently
       set to nonblocking mode,	and configured to be closed on exit(3).

       An application is allowed to unregister a file descriptor  from	within
       any  callback  function,	including callback functions triggered by that
       file descriptor itself, and even	to free	the  memory  corresponding  to
       that file descriptor from any callback function,	but a struct iv_fd can
       only be unregistered in the thread that it was registered from.

       It is allowed to	register the same underlying  OS  file	descriptor  in
       multiple	 threads,  but	a given	struct iv_fd can only be registered in
       one thread at a time.

       iv_fd_register does not return errors to	the caller, and	in case	of  an
       error  while  registering  the file descriptor, for example if it isn't
       open or is unpollable, iv_fatal(2) will be invoked.  If it is not known
       whether	registering  the  file descriptor with the kernel will be suc-
       cessful or not, use iv_fd_register_try instead, which is	a  variant  on
       iv_fd_register  which returns a nonzero value in	case of	a registration
       error.  Since iv_fd_register_try	disables  various  internal  optimisa-
       tions, it is recommended	to use iv_fd_register whenever possible.

       See iv_examples(3) for programming examples.

SEE ALSO
       ivykis(3), iv_examples(3)

ivykis				  2010-08-15			      iv_fd(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=iv_fd_register&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help