xref: /plan9/sys/src/cmd/gs/src/gsnotify.h (revision 593dc095aefb2a85c828727bbfa9da139a49bdf4)
1 /* Copyright (C) 1999 Aladdin Enterprises.  All rights reserved.
2 
3   This software is provided AS-IS with no warranty, either express or
4   implied.
5 
6   This software is distributed under license and may not be copied,
7   modified or distributed except as expressly authorized under the terms
8   of the license contained in the file LICENSE in this distribution.
9 
10   For more information about licensing, please refer to
11   http://www.ghostscript.com/licensing/. For information on
12   commercial licensing, go to http://www.artifex.com/licensing/ or
13   contact Artifex Software, Inc., 101 Lucas Valley Road #110,
14   San Rafael, CA  94903, U.S.A., +1(415)492-9861.
15 */
16 
17 /* $Id: gsnotify.h,v 1.5 2002/06/16 08:45:42 lpd Exp $ */
18 /* Notification machinery */
19 
20 #ifndef gsnotify_INCLUDED
21 #  define gsnotify_INCLUDED
22 
23 #include "gsstype.h"		/* for extern_st */
24 
25 /*
26  * An arbitrary number of clients may register themselves to be notified
27  * when an event occurs.  Duplicate registrations are not detected.  Clients
28  * must unregister themselves when they are being freed (finalized), if not
29  * before.  Objects that provide notification must notify clients when the
30  * object is being freed (finalized): in this event, and only in this event,
31  * event_data = NULL.
32  */
33 
34 /* Define the structure used to keep track of registrations. */
35 #define GS_NOTIFY_PROC(proc)\
36     int proc(void *proc_data, void *event_data)
37 typedef GS_NOTIFY_PROC((*gs_notify_proc_t));
38 typedef struct gs_notify_registration_s gs_notify_registration_t;
39 struct gs_notify_registration_s {
40     gs_notify_proc_t proc;
41     void *proc_data;
42     gs_notify_registration_t *next;
43 };
44 #define private_st_gs_notify_registration() /* in gsnotify.c */\
45   gs_private_st_ptrs2(st_gs_notify_registration, gs_notify_registration_t,\
46     "gs_notify_registration_t", notify_registration_enum_ptrs,\
47     notify_registration_reloc_ptrs, proc_data, next)
48 
49 /* Define a notification list. */
50 typedef struct gs_notify_list_s {
51     gs_memory_t *memory;	/* for allocating registrations */
52     gs_notify_registration_t *first;
53 } gs_notify_list_t;
54 /* The descriptor is public for GC of embedded instances. */
55 extern_st(st_gs_notify_list);
56 #define public_st_gs_notify_list() /* in gsnotify.c */\
57   gs_public_st_ptrs1(st_gs_notify_list, gs_notify_list_t,\
58     "gs_notify_list_t", notify_list_enum_ptrs, notify_list_reloc_ptrs,\
59     first)
60 #define st_gs_notify_list_max_ptrs 1
61 
62 /* Initialize a notification list. */
63 void gs_notify_init(gs_notify_list_t *nlist, gs_memory_t *mem);
64 
65 /* Register a client. */
66 int gs_notify_register(gs_notify_list_t *nlist, gs_notify_proc_t proc,
67 		       void *proc_data);
68 
69 /*
70  * Unregister a client.  Return 1 if the client was registered, 0 if not.
71  * If proc_data is 0, unregister all registrations of that proc; otherwise,
72  * unregister only the registration of that procedure with that proc_data.
73  */
74 int gs_notify_unregister(gs_notify_list_t *nlist, gs_notify_proc_t proc,
75 			 void *proc_data);
76 
77 /* Unregister a client, calling a procedure for each unregistration. */
78 int gs_notify_unregister_calling(gs_notify_list_t *nlist,
79 				 gs_notify_proc_t proc, void *proc_data,
80 				 void (*unreg_proc)(void *pdata));
81 
82 /*
83  * Notify the clients on a list.  If an error occurs, return the first
84  * error code, but notify all clients regardless.
85  */
86 int gs_notify_all(gs_notify_list_t *nlist, void *event_data);
87 
88 /* Release a notification list. */
89 void gs_notify_release(gs_notify_list_t *nlist);
90 
91 #endif /* gsnotify_INCLUDED */
92