root/fdwatch.h

/* */

INCLUDED FROM

   1 /* fdwatch.h - header file for fdwatch package
   2 **
   3 ** This package abstracts the use of the select()/poll()/kqueue()
   4 ** system calls.  The basic function of these calls is to watch a set
   5 ** of file descriptors for activity.  select() originated in the BSD world,
   6 ** while poll() came from SysV land, and their interfaces are somewhat
   7 ** different.  fdwatch lets you write your code to a single interface,
   8 ** with the portability differences hidden inside the package.
   9 **
  10 ** Usage is fairly simple.  Call fdwatch_get_nfiles() to initialize
  11 ** the package and find out how many fine descriptors are available.
  12 ** Then each time through your main loop, call fdwatch_clear(), then
  13 ** fdwatch_add_fd() for each of the descriptors you want to watch,
  14 ** then call fdwatch() to actually perform the watch.  After it returns
  15 ** you can check which descriptors are ready via fdwatch_check_fd().
  16 **
  17 ** If your descriptor set hasn't changed from the last time through
  18 ** the loop, you can skip calling fdwatch_clear() and fdwatch_add_fd()
  19 ** to save a little CPU time.
  20 **
  21 **
  22 ** Copyright (c) 1999 by Jef Poskanzer <jef@mail.acme.com>.
  23 ** Copyright (c) 2023 by Amelia Zabardast Ziabari <ame@psianesia.org>.
  24 ** All rights reserved.
  25 **
  26 ** Redistribution and use in source and binary forms, with or without
  27 ** modification, are permitted provided that the following conditions
  28 ** are met:
  29 ** 1. Redistributions of source code must retain the above copyright
  30 **    notice, this list of conditions and the following disclaimer.
  31 ** 2. Redistributions in binary form must reproduce the above copyright
  32 **    notice, this list of conditions and the following disclaimer in the
  33 **    documentation and/or other materials provided with the distribution.
  34 **
  35 ** THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  36 ** ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  37 ** IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  38 ** ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  39 ** FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  40 ** DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  41 ** OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  42 ** HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  43 ** LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  44 ** OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  45 ** SUCH DAMAGE.
  46 */
  47 
  48 #ifndef _FDWATCH_H_
  49 #define _FDWATCH_H_
  50 
  51 #define FDW_READ 0
  52 #define FDW_WRITE 1
  53 
  54 #ifndef INFTIM
  55 #define INFTIM -1
  56 #endif /* INFTIM */
  57 
  58 /* Figure out how many file descriptors the system allows, and
  59 ** initialize the fdwatch data structures.  Returns -1 on failure.
  60 */
  61 int fdwatch_get_nfiles( void );
  62 
  63 /* Add a descriptor to the watch list.  rw is either FDW_READ or FDW_WRITE.  */
  64 void fdwatch_add_fd( int fd, void* client_data, int rw );
  65 
  66 /* Delete a descriptor from the watch list. */
  67 void fdwatch_del_fd( int fd );
  68 
  69 /* Do the watch.  Return value is the number of descriptors that are ready,
  70 ** or 0 if the timeout expired, or -1 on errors.  A timeout of INFTIM means
  71 ** wait indefinitely.
  72 */
  73 int fdwatch( long timeout_msecs );
  74 
  75 /* Check if a descriptor was ready. */
  76 int fdwatch_check_fd( int fd );
  77 
  78 /* Get the client data for the next returned event.  Returns -1 when there
  79 ** are no more events.
  80 */
  81 void* fdwatch_get_next_client_data( void );
  82 
  83 /* Generate debugging statistics syslog message. */
  84 void fdwatch_logstats( long secs );
  85 
  86 #endif /* _FDWATCH_H_ */

/* */