os/ospoll.h

   1 /*
   2  * Copyright © 2016 Keith Packard
   3  *
   4  * Permission to use, copy, modify, distribute, and sell this software and its
   5  * documentation for any purpose is hereby granted without fee, provided that
   6  * the above copyright notice appear in all copies and that both that copyright
   7  * notice and this permission notice appear in supporting documentation, and
   8  * that the name of the copyright holders not be used in advertising or
   9  * publicity pertaining to distribution of the software without specific,
  10  * written prior permission.  The copyright holders make no representations
  11  * about the suitability of this software for any purpose.  It is provided "as
  12  * is" without express or implied warranty.
  13  *
  14  * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  15  * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
  16  * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  17  * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
  18  * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  19  * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  20  * OF THIS SOFTWARE.
  21  */
  22
  23 #ifndef _OSPOLL_H_
  24 #define _OSPOLL_H_
  25
  26 /* Forward declaration */
  27 struct ospoll;
  28
  29 /**
  30  * ospoll_wait trigger mode
  31  *
  32  * @ospoll_trigger_edge
  33  *      Trigger only when going from no data available
  34  *      to data available.
  35  *
  36  * @ospoll_trigger_level
  37  *      Trigger whenever there is data available
  38  */
  39 enum ospoll_trigger {
  40     ospoll_trigger_edge,
  41     ospoll_trigger_level
  42 };
  43
  44 /**
  45  * Create a new ospoll structure
  46  */
  47 struct ospoll *
  48 ospoll_create(void);
  49
  50 /**
  51  * Destroy an ospoll structure
  52  *
  53  * @param       ospoll          ospoll to destroy
  54  */
  55 void
  56 ospoll_destroy(struct ospoll *ospoll);
  57
  58 /**
  59  * Add a file descriptor to monitor
  60  *
  61  * @param       ospoll          ospoll to add to
  62  * @param       fd              File descriptor to monitor
  63  * @param       trigger         Trigger mode for ospoll_wait
  64  * @param       callback        Function to call when triggered
  65  * @param       data            Extra data to pass callback
  66  */
  67 Bool
  68 ospoll_add(struct ospoll *ospoll, int fd,
  69            enum ospoll_trigger trigger,
  70            void (*callback)(int fd, int xevents, void *data),
  71            void *data);
  72
  73 /**
  74  * Remove a monitored file descriptor
  75  *
  76  * @param       ospoll          ospoll to remove from
  77  * @param       fd              File descriptor to stop monitoring
  78  */
  79 void
  80 ospoll_remove(struct ospoll *ospoll, int fd);
  81
  82 /**
  83  * Listen on additional events
  84  *
  85  * @param       ospoll          ospoll monitoring fd
  86  * @param       fd              File descriptor to change
  87  * @param       events          Additional events to trigger on
  88  */
  89 void
  90 ospoll_listen(struct ospoll *ospoll, int fd, int xevents);
  91
  92 /**
  93  * Stop listening on events
  94  *
  95  * @param       ospoll          ospoll monitoring fd
  96  * @param       fd              File descriptor to change
  97  * @param       events          events to stop triggering on
  98  */
  99 void
 100 ospoll_mute(struct ospoll *ospoll, int fd, int xevents);
 101
 102 /**
 103  * Wait for events
 104  *
 105  * @param       ospoll          ospoll to wait on
 106  * @param       timeout         < 0 wait forever
 107  *                              = 0 check and return
 108  *                              > 0 timeout in milliseconds
 109  * @return      < 0 error
 110  *              = 0 timeout
 111  *              > 0 number of events delivered
 112  */
 113 int
 114 ospoll_wait(struct ospoll *ospoll, int timeout);
 115
 116 /**
 117  * Reset edge trigger status
 118  *
 119  * @param       ospoll          ospoll monitoring fd
 120  * @param       fd              file descriptor
 121  *
 122  * ospoll_reset_events resets the state of an edge-triggered
 123  * fd so that ospoll_wait calls will report events again.
 124  *
 125  * Call this after a read/recv operation reports no more data available.
 126  */
 127 void
 128 ospoll_reset_events(struct ospoll *ospoll, int fd);
 129
 130 /**
 131  * Fetch the data associated with an fd
 132  *
 133  * @param       ospoll          ospoll monitoring fd
 134  * @param       fd              file descriptor
 135  *
 136  * @return      data parameter passed to ospoll_add call on
 137  *              this file descriptor
 138  */
 139 void *
 140 ospoll_data(struct ospoll *ospoll, int fd);
 141
 142 #endif /* _OSPOLL_H_ */