michael@0: /*
michael@0:  * Copyright (c) 2009-2012 Niels Provos and Nick Mathewson
michael@0:  *
michael@0:  * Redistribution and use in source and binary forms, with or without
michael@0:  * modification, are permitted provided that the following conditions
michael@0:  * are met:
michael@0:  * 1. Redistributions of source code must retain the above copyright
michael@0:  *    notice, this list of conditions and the following disclaimer.
michael@0:  * 2. Redistributions in binary form must reproduce the above copyright
michael@0:  *    notice, this list of conditions and the following disclaimer in the
michael@0:  *    documentation and/or other materials provided with the distribution.
michael@0:  * 3. The name of the author may not be used to endorse or promote products
michael@0:  *    derived from this software without specific prior written permission.
michael@0:  *
michael@0:  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
michael@0:  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
michael@0:  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
michael@0:  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
michael@0:  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
michael@0:  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
michael@0:  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
michael@0:  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
michael@0:  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
michael@0:  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
michael@0:  */
michael@0: #ifndef _CHANGELIST_H_
michael@0: #define _CHANGELIST_H_
michael@0: 
michael@0: /*
michael@0:   A "changelist" is a list of all the fd status changes that should be made
michael@0:   between calls to the backend's dispatch function.  There are a few reasons
michael@0:   that a backend would want to queue changes like this rather than processing
michael@0:   them immediately.
michael@0: 
michael@0:     1) Sometimes applications will add and delete the same event more than
michael@0:        once between calls to dispatch.  Processing these changes immediately
michael@0:        is needless, and potentially expensive (especially if we're on a system
michael@0:        that makes one syscall per changed event).
michael@0: 
michael@0:     2) Sometimes we can coalesce multiple changes on the same fd into a single
michael@0:        syscall if we know about them in advance.  For example, epoll can do an
michael@0:        add and a delete at the same time, but only if we have found out about
michael@0:        both of them before we tell epoll.
michael@0: 
michael@0:     3) Sometimes adding an event that we immediately delete can cause
michael@0:        unintended consequences: in kqueue, this makes pending events get
michael@0:        reported spuriously.
michael@0:  */
michael@0: 
michael@0: #include "event2/util.h"
michael@0: 
michael@0: /** Represents a */
michael@0: struct event_change {
michael@0: 	/** The fd or signal whose events are to be changed */
michael@0: 	evutil_socket_t fd;
michael@0: 	/* The events that were enabled on the fd before any of these changes
michael@0: 	   were made.  May include EV_READ or EV_WRITE. */
michael@0: 	short old_events;
michael@0: 
michael@0: 	/* The changes that we want to make in reading and writing on this fd.
michael@0: 	 * If this is a signal, then read_change has EV_CHANGE_SIGNAL set,
michael@0: 	 * and write_change is unused. */
michael@0: 	ev_uint8_t read_change;
michael@0: 	ev_uint8_t write_change;
michael@0: };
michael@0: 
michael@0: /* Flags for read_change and write_change. */
michael@0: 
michael@0: /* If set, add the event. */
michael@0: #define EV_CHANGE_ADD     0x01
michael@0: /* If set, delete the event.  Exclusive with EV_CHANGE_ADD */
michael@0: #define EV_CHANGE_DEL     0x02
michael@0: /* If set, this event refers a signal, not an fd. */
michael@0: #define EV_CHANGE_SIGNAL  EV_SIGNAL
michael@0: /* Set for persistent events.  Currently not used. */
michael@0: #define EV_CHANGE_PERSIST EV_PERSIST
michael@0: /* Set for adding edge-triggered events. */
michael@0: #define EV_CHANGE_ET      EV_ET
michael@0: 
michael@0: /* The value of fdinfo_size that a backend should use if it is letting
michael@0:  * changelist handle its add and delete functions. */
michael@0: #define EVENT_CHANGELIST_FDINFO_SIZE sizeof(int)
michael@0: 
michael@0: /** Set up the data fields in a changelist. */
michael@0: void event_changelist_init(struct event_changelist *changelist);
michael@0: /** Remove every change in the changelist, and make corresponding changes
michael@0:  * in the event maps in the base.  This function is generally used right
michael@0:  * after making all the changes in the changelist. */
michael@0: void event_changelist_remove_all(struct event_changelist *changelist,
michael@0:     struct event_base *base);
michael@0: /** Free all memory held in a changelist. */
michael@0: void event_changelist_freemem(struct event_changelist *changelist);
michael@0: 
michael@0: /** Implementation of eventop_add that queues the event in a changelist. */
michael@0: int event_changelist_add(struct event_base *base, evutil_socket_t fd, short old, short events,
michael@0:     void *p);
michael@0: /** Implementation of eventop_del that queues the event in a changelist. */
michael@0: int event_changelist_del(struct event_base *base, evutil_socket_t fd, short old, short events,
michael@0:     void *p);
michael@0: 
michael@0: #endif