ntfy.h

操作系统SunOS 4.1.3版本的源码

/*	@(#)ntfy.h 1.1 92/07/30 SMI	*/

/*
 * Copyright (c) 1985 by Sun Microsystems, Inc.
 */

/*
 * Ntfy.h - Private header file for the implementation of the notifier.
 * Contains definitions common to the two major parts (dectector &
 * dispather) of the notifier.
 */

#ifndef	NTFY_DEFINED
#define	NTFY_DEFINED

#include <sys/types.h>
#include <sys/time.h>
#include <sys/resource.h>
#include <sys/wait.h>
#include <sunwindow/notify.h>

#ifdef	COMMENT
********************** Implementation Goals ****************************
Here are the major goals of the implementation of the notifier,
other than faithfully supporting the programming interface:

1) The implementation should be fast in common cases.  In particular,
the select, notify of input pending, notify of client event, back to
select again loop must be very efficient.

2) The implementation should be clean and general so that it
is easy to understand, extend and maintain.  This code will be
combed over heavily either to extend or debug it.

3) The implementation should be safe for asynchronous client event
notifications.  Reenterant calls must be safe, i.e., before
calling out to the client, data structures must be in a consistent state.


********************** Implementation Division *************************
The notifier will be divided internally into two basic parts:

1) The detector is responsible for noticing the occurrence of UNIX
events.  It maintains a complete list of clients that are awaiting
notification.  It maintains a per client list of conditions that the
client is awaiting.

2) The dispatcher is responsible for actual delivery of notifications
to clients.  It maintains a list of clients with notifications pending.
It maintains a per client queue of conditions that have already
happened.

The two parts of the notifier will share the same critical section
protections scheme (described below).

The public programming interface that each part of the notifier
supports is described in the each of two header files ndec.h & ndis.h.

Data and definitions shared between the detector and dispatcher
are contained in ntfy.h (ntfy_/NTFY_ name prefices).
Notifier public data structures and constants have
are contained in notify.h (notify_/NOTIFY_ name prefices).

#endif	COMMENT

/*
 * Ntfy_client defines the notifier's view of a client.
 */
typedef struct	ntfy_client {
	struct	ntfy_client *next;	/* Next client in list (this field must
					   be the first in the structure) */
	Notify_client nclient;		/* Client's private data handle */
	struct	ntfy_condition *conditions;
					/* Linked list of clients */
	struct	ntfy_condition *condition_latest;
					/* Hint when searching conditions */
	Notify_value (*prioritizer)();	/* Function to call to do notification
					   prioritization (defaults if null) */
	u_int	flags;			/* Per client boolean state */
#define	NCLT_EVENT_PROCESSING	0x01	/* Dispatcher in process of notifying
					   client of client event */
} NTFY_CLIENT;
#define	NTFY_CLIENT_NULL	((NTFY_CLIENT *)0)

/*
 * Ntfy_type defines the types of conditions that the notifier supports.
 */
typedef enum ntfy_type {
	NTFY_UNKNOWN=0,
	NTFY_INPUT=1,
	NTFY_OUTPUT=2,
	NTFY_EXCEPTION=3,
	NTFY_SYNC_SIGNAL=4,
	NTFY_ASYNC_SIGNAL=5,
	NTFY_REAL_ITIMER=6,
	NTFY_VIRTUAL_ITIMER=7,
	NTFY_WAIT3=8,
	NTFY_SAFE_EVENT=9,
	NTFY_IMMEDIATE_EVENT=10,
	NTFY_DESTROY=11,
} NTFY_TYPE;

/*
 * Ntfy_condition defines the notifier's view of a condition.
 * For conditions that have more than 32 bits of additional information,
 * dynamically allocate a node to hold this data.
 */
typedef struct ntfy_condition {
	struct	ntfy_condition *next;	/* Next condition for client (this field
					   must be the first in the structure)*/
	enum	ntfy_type type;		/* Type of condition */
	char	func_count;		/* Number of functions managing */
	char	func_next;		/* Next function to call */
	union	{			/* Switch on func_count > 1 */
		Notify_func function;	/* Notification function */
		Notify_func *functions;	/* Array of interposed functions */
#define	NTFY_FUNCS_MAX	(sizeof(NTFY_NODE)/sizeof(Notify_func))
	} callout;
	union {				/* Type specific data */
		int	fd;		/* NTFY_INPUT, NTFY_OUTPUT,
					   NTFY_EXCEPTION */
		int	signal;		/* NTFY_*_SIGNAL */
		u_int	an_u_int;	/* Generic unsigned int used for
					   instance matching */
		Notify_event event;	/* NTFY_*_EVENT */
		Destroy_status status;	/* NTFY_DESTROY */
		struct	ntfy_itimer *ntfy_itimer;
					/* NTFY_*_ITIMER (ndet only)
					   malloced struct */
		struct	ntfy_wait3_data *wait3;	/* NTFY_WAIT3 (ndis only)
					   malloced struct */
		int	pid;		/* NTFY_WAIT3 (ndet only) */
	} data;
	Notify_arg arg;			/* Event arg (ndis only) */
	Notify_release release;		/* arg release func (ndis only) */
} NTFY_CONDITION;
#define	NTFY_CONDITION_NULL	((NTFY_CONDITION *)0)
#define	NTFY_ITIMER_NULL	((struct itimerval *)0)
#define	NTFY_TIMEVAL_NULL	((struct timeval *)0)

/*
 * Ntfy_wait3_data is additional data for the NTFY_WAIT3 condition.
 */
typedef	struct ntfy_wait3_data {
	int	pid;			/* Process waiting for */
	union	wait status;		/* Return value from wait3 */
	struct	rusage rusage;		/* Return value from wait3 */
} NTFY_WAIT3_DATA;
#define	NTFY_WAIT3_DATA_NULL	((NTFY_WAIT3_DATA *)0)

/*
 * Ntfy_itimer is additional data for the NTFY_*_ITIMER condition.
 */
typedef	struct ntfy_itimer {
	struct	itimerval itimer;	/* REAL: Client passed in itimer */
					/* VIRTUAL: Client passed in itimer but
					   with it_value decremented to current
					   interval until expiration */
	struct	timeval set_tv;		/* REAL: Time-of-day when set (or reset)
					   the condition */
					/* VIRTUAL: Most recent interval to
					   which the process virtual itimer
					   was set */
} NTFY_ITIMER;

/*
 * Shared global private data
 */
extern	int ntfy_sigs_blocked;	/* count of nesting of signal blocking*/
extern	int ntfy_interrupts;	/* count of interrupts handling (0 or 1) */
extern	int ntfy_nodes_avail;	/* count of nodes available without having
				   to go to the system heap */
extern	u_int ntfy_sigs_delayed;/* Bit mask of signals received while in
				   critical section */

/*
 * Critical section protection macros.  A critical section is any section
 * of code that modifies or uses global data.  Details below.
 */
#define	NTFY_BEGIN_CRITICAL	ntfy_sigs_blocked++
#define	NTFY_IN_CRITICAL	(ntfy_sigs_blocked > 0)
#define	NTFY_END_CRITICAL   	ntfy_end_critical()
void	ntfy_end_critical();

/*
 * Interrupt detection macros.  Set when processing at signal interrupt
 * level.  Explanation below.
 */
#define	NTFY_BEGIN_INTERRUPT	ntfy_interrupts++
#define	NTFY_IN_INTERRUPT	(ntfy_interrupts > 0)
#define	NTFY_END_INTERRUPT   	ntfy_interrupts--

/*
 * Storage management definitions.  Details below.
 */
typedef	struct	ntfy_node {
	union {	/* List all data types that use the allocator */
		/* Extra data for NTFY_CONDITION */
		NTFY_ITIMER ntfy_itimer;
		/* Other structs that use nodes */
		NTFY_CLIENT client;
		NTFY_CONDITION condition;
		struct	ntfy_node *next;
	} n;
} NTFY_NODE;
#define	NTFY_NODE_NULL	((NTFY_NODE *)0)

typedef	enum	ntfy_enum {		/* Enumeration return values */
	NTFY_ENUM_NEXT=0,		/* Next condition please (normal) */
	NTFY_ENUM_TERM=1,		/* Enumeration terminated in middle */
	NTFY_ENUM_SKIP=2,		/* Skip rest of conditions in client */
} NTFY_ENUM;
typedef	NTFY_ENUM (*NTFY_ENUM_FUNC)();
#define	NTFY_ENUM_FUNC_NULL	((NTFY_ENUM_FUNC)0)
typedef	caddr_t	NTFY_ENUM_DATA;
#define	NTFY_ENUM_DATA_NULL	((NTFY_ENUM_DATA)0)
typedef	caddr_t	NTFY_DATA;
#define	NTFY_DATA_NULL		((NTFY_DATA)0)
#define	NTFY_DATA_PTR_NULL	((NTFY_DATA *)0)

#define	NTFY_PRE_ALLOCED_MIN	10	/* Min pre-allocated nodes that must
					   be available before notify interrupt
					   (asynchronous) signal handler */
#define	NTFY_SIGS_PER_LOOP	3	/* Reasonable number of signals that
					   might expect between each
					   notification loop */
#define	NTFY_PRE_ALLOCED	(NTFY_PRE_ALLOCED_MIN*NTFY_SIGS_PER_LOOP)
					/* Number of nodes kept pre-allocated */
#define	NTFY_NODE_BYTES		sizeof(NTFY_NODE)
					/* NTFY_NODE_BYTES is the node size
					   that use the storage allocator */
#define	NTFY_MIN_NODES		22	/* Reasonable number of conditions per
					   normal application */
#define	NTFY_NODES_PER_BLOCK	(NTFY_PRE_ALLOCED+(NTFY_MIN_NODES*2))
					/* Number of nodes allocated every time
					   go to heap (2 accounts for each
					   condition taking 2 nodes, one for
					   detector and one for dispatcher) */