eventio API

Hi fellow Squid hackers.

Attached is a suggestion for the new API to the upcoming eventdriven
network I/O layer. Comments are welcome.

The goal of this layer is to abstract most of the
select/poll/read/write/whatever issues from the rest of the code,
allowing the I/O to be implemented in an much more efficient manner
using the primitives available on the platform.

Note: The initial implementation will be poll() driven, but adding other
implementations like select, /dev/poll, Win32 completetion ports (is
this the correct term?) or whatever is only a matter of implementing
them ;-)

/Henrik

. Network I/O

   The networking I/O layer is responsible for all network I/O (duh!).
   
   It is implemented as a set of asyncronous operations for opening /
   acception connections and reading/writing data on those connections.
   The asyncronous operation means that each API call will only initiate
   the operation, and when the operation s finished a supplied callback
   function will be called.
   
   Created filehandles are cbdata enabled, and any links / pointers to
   filehandles should be properly managed as cbdata.
   
   The return value of is 0 on success or -1 on error. On error, errno
   will be set to a suitable error code.
   
.1 API

  ncomm_close
  
        int
        ncomm_close(filehandle *fh);

   Closes down the socket once all pending data has been sent.
   
  ncomm_abort
  
        int
        ncomm_abort(filehandle *fh);

   Aborts the given network connection immediately. Any pending I/O
   requests will be aborted.
   
  ncomm_listen
  
        int
        ncomm_listen(int sock_type, int proto, struct sockaddr *where,
                     int addrsize, COMMNEWCB *callback, void *cbdata)

   start listening for new connections on the given address/port.
   
  ncomm_accept
  
   preleminary draft: This should probably only accept one connection.
   
        int
        ncomm_accept(int sock_type, int proto, struct sockaddr *where,
                     struct sockaddr *from, int addrsize,
                     COMMNEWCB callback, void *cbdata)

   Like comm_listen, but only accept connections from the given source
   
  ncomm_connect
  
        int
        ncomm_connect(int sock_type, int proto,
                      const struct sockaddr *local,
                      const struct sockaddr *remote, int addrsize,
                      COMMNEWCB *callback, void *data)

   Creates a new network connection to the given remote address,
   optionally using a specified local source address.
   
  ncomm_read
  
 void
        ncomm_read(filehandle *fh, IOBUF *buf, size_t min_size,
                   size_t max_size, COMMIOCB *callback, void *data);

   request to read some data. buf might be specified as NULL in which
   case a IOBUF will be allocated to keep the data read from the network.
   
   Any errors will be signalled to the callback function.
   
  ncomm_write
  
        void
        ncomm_write(filehandle *fh, IOBUF *buf, off_t offset,
                    size_t size, COMMIOCB *callback, void *data);

   request to write some data.
   
   if size is 0 then all data in the buffer will be written.
   
   it is allowable to queue more write requests before the first has
   finished. The requests will be processed in the order requested.
   
   Any errors will be signalled to the callback function.
   
  ncomm_add_close_handler
  
        int
        ncomm_add_close_handler(filehandle *fh, COMMCLOSECB *handler,
                                void *cbdata);

   Registers a close handler what will be called when the socket is
   closed. For example to clean up associated data structures or keep
   relations proper.
   
.2 "system" API

  ncomm_init
  
        void
        ncomm_module_init(void);

   Initializes the network I/O subsystem
   
  ncomm_abort_all_connections
  
   Do we really need this?
   
        void
        ncomm_abort_all_connections(void);

   Aborts all currently open network connections.
   
  ncomm_module_shutdown
  
        void
        ncomm_module_shutdown(void);

   Called on shutdown. Terminates all pendin I/O operations and/or
   connections and other related cleanups.
   
.3 callbacks

  COMMNEWCB
  
        typedef void
        COMMNEWCB(filehandle *fh, struct sockaddr *local,
                  struct sockaddr *peer, void *cbdata);

   Called when a new filehandle is created (ncomm_listen / ncomm_accept /
   ncomm_connect)
   
  COMMIOCB
  
        typedef void
        COMMIOCB(filehandle *fh, IOBUF *buf, int offset, int size,
                 int errno, void *cbdata);

   Called when an I/O operation has finished.
   
   On error, errno will be set to the error verb.
   
  COMMCLOSECB
  
        typedef void
        COMMCLOSECB(filehandle *fh, void *cbdata);

   Called when the filehandle is closed (ncomm_close / ncomm_abort), as
   requested (ncomm_add_close_handler)
     _________________________________________________________________
Received on Mon Feb 19 2001 - 15:25:31 MST