/src/google/protobuf-c/protobuf-c-dispatch.h

/*
 * Copyright (c) 2008-2011, Dave Benson.
 * 
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with
 * or without modification, are permitted provided that the
 * following conditions are met:
 * 
 * Redistributions of source code must retain the above
 * copyright notice, this list of conditions and the following
 * disclaimer.

 * Redistributions in binary form must reproduce
 * the above copyright notice, this list of conditions and
 * the following disclaimer in the documentation and/or other
 * materials provided with the distribution.
 *
 * Neither the name
 * of "protobuf-c" nor the names of its contributors
 * may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
 * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER
 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef __PROTOBUF_C_DISPATCH_H_
#define __PROTOBUF_C_DISPATCH_H_

typedef struct _ProtobufCDispatch ProtobufCDispatch;
typedef struct _ProtobufCDispatchTimer ProtobufCDispatchTimer;
typedef struct _ProtobufCDispatchIdle ProtobufCDispatchIdle;

#include "protobuf-c.h"

typedef enum
{
  PROTOBUF_C_EVENT_READABLE = (1<<0),
  PROTOBUF_C_EVENT_WRITABLE = (1<<1)
} ProtobufC_Events;

#ifdef WIN32
typedef SOCKET ProtobufC_FD;
#else
typedef int ProtobufC_FD;
#endif

/* Create or destroy a Dispatch */
ProtobufCDispatch  *protobuf_c_dispatch_new (ProtobufCAllocator *allocator);
void                protobuf_c_dispatch_free(ProtobufCDispatch *dispatch);

ProtobufCDispatch  *protobuf_c_dispatch_default (void);

ProtobufCAllocator *protobuf_c_dispatch_peek_allocator (ProtobufCDispatch *);

typedef void (*ProtobufCDispatchCallback)  (ProtobufC_FD   fd,
                                            unsigned       events,
                                            void          *callback_data);

/* Registering file-descriptors to watch. */
void  protobuf_c_dispatch_watch_fd (ProtobufCDispatch *dispatch,
                                    ProtobufC_FD        fd,
                                    unsigned            events,
                                    ProtobufCDispatchCallback callback,
                                    void               *callback_data);
void  protobuf_c_dispatch_close_fd (ProtobufCDispatch *dispatch,
                                    ProtobufC_FD        fd);
void  protobuf_c_dispatch_fd_closed(ProtobufCDispatch *dispatch,
                                    ProtobufC_FD        fd);

/* Timers */
typedef void (*ProtobufCDispatchTimerFunc) (ProtobufCDispatch *dispatch,
                                            void              *func_data);
ProtobufCDispatchTimer *
      protobuf_c_dispatch_add_timer(ProtobufCDispatch *dispatch,
                                    unsigned           timeout_secs,
                                    unsigned           timeout_usecs,
                                    ProtobufCDispatchTimerFunc func,
                                    void               *func_data);
ProtobufCDispatchTimer *
      protobuf_c_dispatch_add_timer_millis
                                   (ProtobufCDispatch *dispatch,
                                    unsigned           milliseconds,
                                    ProtobufCDispatchTimerFunc func,
                                    void               *func_data);
void  protobuf_c_dispatch_remove_timer (ProtobufCDispatchTimer *);

/* Idle functions */
typedef void (*ProtobufCDispatchIdleFunc)   (ProtobufCDispatch *dispatch,
                                             void               *func_data);
ProtobufCDispatchIdle *
      protobuf_c_dispatch_add_idle (ProtobufCDispatch *dispatch,
                                    ProtobufCDispatchIdleFunc func,
                                    void               *func_data);
void  protobuf_c_dispatch_remove_idle (ProtobufCDispatchIdle *);

/* --- API for use in standalone application --- */
/* Where you are happy just to run poll(2). */

/* protobuf_c_dispatch_run() 
 * Run one main-loop iteration, using poll(2) (or some system-level event system);
 * 'timeout' is in milliseconds, -1 for no timeout.
 */
void  protobuf_c_dispatch_run      (ProtobufCDispatch *dispatch);


/* --- API for those who want to embed a dispatch into their own main-loop --- */
typedef struct {
  ProtobufC_FD fd;
  ProtobufC_Events events;
} ProtobufC_FDNotify;

typedef struct {
  ProtobufC_FD fd;
  ProtobufC_Events old_events;
  ProtobufC_Events events;
} ProtobufC_FDNotifyChange;

void  protobuf_c_dispatch_dispatch (ProtobufCDispatch *dispatch,
                                    size_t              n_notifies,
                                    ProtobufC_FDNotify *notifies);
void  protobuf_c_dispatch_clear_changes (ProtobufCDispatch *);


struct _ProtobufCDispatch
{
  /* changes to the events you are interested in. */
  /* (this handles closed file-descriptors 
     in a manner agreeable to epoll(2) and kqueue(2)) */
  size_t n_changes;
  ProtobufC_FDNotifyChange *changes;

  /* the complete set of events you are interested in. */
  size_t n_notifies_desired;
  ProtobufC_FDNotify *notifies_desired;

  /* number of milliseconds to wait if no events occur */
  protobuf_c_boolean has_timeout;
  unsigned long timeout_secs;
  unsigned timeout_usecs;

  /* true if there is an idle function, in which case polling with
     timeout 0 is appropriate */
  protobuf_c_boolean has_idle;

  unsigned long last_dispatch_secs;
  unsigned last_dispatch_usecs;

  /* private data follows (see RealDispatch structure in .c file) */
};

void protobuf_c_dispatch_destroy_default (void);

#endif