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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=iv_fd_set_handler_err&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help