#ifndef __CALLOUT_H__
#define __CALLOUT_H__


/*
 * callout.h
 *
 * Register event callouts.  Callouts are useful as a way to structure control
 * transfers from lower levels of a system to higher levels. Callouts are
 * performed in response to certained pre-defined system events that might
 * typically be generated by hardware.
 *
 *
 *
 * HISTORY
 * 30-Mar-98  Brian Bershad (bershad) at the University of Washington
 *	Created.
 *
 */


/*
 * A callout event function is registered for various events.  There can be
 * more than one callout event function per event type. A callout event function
 * takes three arguments: the event type itself, the callout handle,
 * and a closure specified at callout registration time.
 *	
 */

#ifndef FALSE
#define FALSE 0
#endif
#ifndef TRUE
#define TRUE 1
#endif

typedef void *callout_event_data_t;
typedef void *callout_event_closure_t;
typedef void* callout_id_t;	/* callout handle */
#define CALLOUT_ID_NULL	(callout_id_t)0



/*
 * Event Types
 */

#define CALLOUT_EVENT_NULL	0
#define CALLOUT_EVENT_CLOCK	1		
#define CALLOUT_EVENT_NETWORK	2
#define CALLOUT_EVENT_DISK	3
#define CALLOUT_EVENT_PAGEFAULT	4
#define CALLOUT_EVENT_TTY	5
#define CALLOUT_EVENT_LAST	6

typedef void (*callout_event_func_t)(int type,
				    callout_id_t h,
				    callout_event_closure_t cl);


/*
 * callout_register installs the specified function f on the event.
 * It returns a handle to the callout routine that can be used
 * for subsequent manipulation.  Returns CALLOUT_ID_NULL if the callout
 * can not be registered.
 */
 
callout_id_t
callout_register(int type,
		 callout_event_func_t f,
		 callout_event_closure_t c);

/*
 * callout_unregister removes the specified callout. Any registered
 * closure is returned as well for freeing if necessary.
 * Return TRUE for success, FALSE for failure.
 */

int
callout_unregister(callout_id_t h, callout_event_closure_t *c);


/*
 * Return the number of calls made on a given callout id_t. Return TRUE for success,
 * FALSE for failure (eg, bad handle)
 */

int
callout_getstats(callout_id_t h,
		 int *numcalls);




/*
 * callout_map can be used to map a given callout_map_func_t over
 * all of the callout functions.  It would typically be used to find something
 * in the callout table, or to print out some global statistic, as in:
 *
 *
 *
 *	
 * 	void mapcount(int type, callout_map_closure_t mapcl,
 *		      callout_id_t h, callout_event_closure_t cl)
 * 	{
 *	   int n;
 *          if (callout_getstats(h, &n) == FALSE) {
 *	      printf("Bad Handle\n");
 *          } else  {
 *	     int *np = (int*)mapcl;
 *           (*np) += n
 *          }
 *	}   
 *
 *	int
 *	count_callouts()
 *	{  numcalls = 0;
 *	   callout_map(mapcount, &numcalls);
 *	   printf("Result is %d\n", numcalls);
 *      }
 */

typedef void *callout_map_closure_t ;

typedef void (*callout_map_func_t)(int type,
				   callout_map_closure_t mapcl,
				   callout_id_t h,
				   callout_event_closure_t cl);
void
callout_map(callout_map_func_t mapf,
	    callout_map_closure_t cl);





/*
 * A callout_genevent_func_t returns an instance of a callout event type.
 */


typedef int (*callout_genevent_func_t)(void);
    
    
/*
 * callout_boot starts generating callout events until callout_shutdown
 * is called. The paramter genevent() is expected to generate a callout
 * event every time it is called. It returns a integer representing 
 * the event type and optionally updates any global variables related to
 * the event. It basically simlates an interrupt.
 */

void
callout_boot(callout_genevent_func_t genevent);



/*
 * callout_shutdown should be called to shutdown the system.  The system
 * will generate no more callout events. This function could be called
 * from the genevent() function passed into callout_boot()
 */
    
void
callout_shutdown();


#endif __CALLOUT_H__