PIOMan's Documentation

This should be PIOMan's documentation. For now, it is very brief, but if you have any question, feel free to send an email to trahay@labri.fr.

Files

  • include/pioman.h: main header file (the file to be included in your application/library)
  • include/piom.{c|h}: contains functions related to PIOMan's interface (piom_wait, piom_req_wait, etc.)
  • include/piom_req_handling.{c|h}: contains everything related to requests (definition, initialization functions, etc.)
  • include/piom_server.{c|h}: contains everything related to PIOMan's servers (definition, initialization functions, etc.)
  • include/piom_lock.{c|h}: contains definitions of locks (with and without Marcel) that can be used in applications (for instance in NewMadeleine) or within PIOMan
  • include/piom_iterator.h: header file that contains macros usefull to iterate over PIOMan's lists
  • include/piom_block.{c|h}: contains functions related to blocking syscalls
  • include/piom_poll.{c|h}: contains functions related to polling
  • include/piom_sem.{c|h}: contains semaphore and condition definitions (with and without Marcel)
  • include/piom_sh_sem.{c|h}: contains shared-memory semaphore functions (used within MPICH2-Nemesis)
  • include/piom_debug.h: contains debugging macros
  • include/piom_log.h: logging subsystem header
  • include/piom_io.{c|h}: Socket event subsystem based on PIOMan. These files can be used as example to understand PIOMan's utilization

PIOMan's interface

PIOMan is based on 'servers' that correspond to types of events : typedef struct piom_server *piom_server_t;

For example, NewMadeleine may use 2 servers to poll 2 different networks.

Each server defines callbacks used to poll events. These callbacks may be of different kinds :

/* Available kinds of callbacks */
typedef enum {
PIOM_FUNCTYPE_POLL_POLLONE, /* the callback polls a specific query */
PIOM_FUNCTYPE_POLL_GROUP, /* the callback groups queries */
PIOM_FUNCTYPE_POLL_POLLANY, /* the callback polls every submitted query */
PIOM_FUNCTYPE_BLOCK_WAITONE, /* the callback exports a syscall to complete a specific query */
PIOM_FUNCTYPE_BLOCK_WAITONE_TIMEOUT, /* idem with a timeout */
PIOM_FUNCTYPE_BLOCK_GROUP, /* the callback groups queries to be exported */
PIOM_FUNCTYPE_BLOCK_WAITANY, /* the callback completes every submitted query using an exported syscall */
PIOM_FUNCTYPE_BLOCK_WAITANY_TIMEOUT, /* idem with a timeout */
PIOM_FUNCTYPE_UNBLOCK_WAITONE, /* unblocks a query blocked with PIOM_FUNCTYPE_BLOCK_WAITONE */
PIOM_FUNCTYPE_UNBLOCK_WAITANY, /* unblocks a query blocked with PIOM_FUNCTYPE_BLOCK_WAITANY */
PIOM_FUNCTYPE_SIZE /* PRIVATE */
} piom_op_t;

Q: How do I add a callback ?

An example is given in the piom_io.c file:

piom_server_add_callback(&piom_io_server.server,   /* server for which the callback is added */
		  PIOM_FUNCTYPE_POLL_POLLONE, /* callback type */
		  (piom_pcallback_t) {
		    .func = &piom_io_fast_poll, /* function to use */
                          .speed = PIOM_CALLBACK_SLOWEST /* function speed (unused for now) */
                          }
                        );

Q: How do I create a callback ?

The piom_io.c file contains an example of callback: piom_io_poll. This callback polls a file descriptor:

 static int piom_io_fast_poll(piom_server_t server, 
		        piom_op_t _op,
		        piom_req_t req, /* Request to be polled */
                              int nb_ev, 
                              int option)
 {
      /* Get the file descriptor, etc. from the request structure */
piom_tcp_ev_t ev = struct_up(req, struct piom_tcp_ev, inst);
      ...
      select(...);
      ...
      if(success)
         piom_req_success(&req);
      ...
 }

Q: How do I submit a request ?

There are 3 ways to wait for a request :

* Using piom_wait: piom_wait registers a request, waits for it and unregister the request

int piom_wait(piom_server_t server, piom_req_t req,
       piom_wait_t wait, piom_time_t timeout)
 /* An example is given in piom_io.c */
int piom_read(int fildes, void *buf, size_t nbytes)
{
int n;
struct piom_tcp_ev ev;
struct piom_wait wait;
LOG_IN();
PROF_EVENT(piom_read_entry);
/* Pour eviter de demander à un serveur qui n'est pas lancé */
if(piom_io_server.server.state==PIOM_SERVER_STATE_LAUNCHED)
{	
	do {
		ev.op = PIOM_POLL_READ;
		ev.FD = fildes;
		PIOM_LOGF("Reading in fd %i\n", fildes);
		piom_wait(&piom_io_server.server, &ev.inst, &wait, 0);
		LOG("IO reading fd %i", fildes);
		n = read(fildes, buf, nbytes);
	} while (n == -1 && errno == EINTR);
	PROF_EVENT(piom_read_exit);
	LOG_RETURN(n);
}else
	LOG_RETURN(read(fildes, buf, nbytes));
}

Inside PIOMan

Does anybody really want to understand PIOMan's inside behavior ?

Yes!

pioman.txt · Last modified: 2008/10/13 13:40 by trahay
 
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki