Working on babel/library support
[projects/chimara/chimara.git] / libchimara / dispatch.c
1 #include <libchimara/glk.h>
2 #include "chimara-glk-private.h"
3 #include "window.h"
4 #include "stream.h"
5 #include "fileref.h"
6 #include "schannel.h"
7
8 extern GPrivate *glk_data_key;
9
10 /**
11  * gidispatch_set_object_registry:
12  * @regi: Function to call whenever an opaque object is created.
13  * @unregi: Function to call whenever an opaque object is destroyed.
14  *
15  * The Glk API refers to opaque objects by pointer; but a VM probably cannot 
16  * store pointers to native memory. Therefore, a VM program will want to keep a
17  * VM-accessible collection of opaque objects.
18  * 
19  * <note><para>
20  *   For example, it might keep a hash table for each opaque object class,
21  *   mapping integer identifiers to object pointers.
22  * </para></note>
23  * 
24  * To make this possible, a Glk library must implement 
25  * gidispatch_set_object_registry().
26  * 
27  * Your program calls gidispatch_set_object_registry() early (before it begins
28  * actually executing VM code.) You pass in two function pointers, matching the
29  * following prototypes:
30  * |[
31  * gidispatch_rock_t my_vm_reg_object(void *obj, glui32 objclass);
32  * void my_vm_unreg_object(void *obj, glui32 objclass, gidispatch_rock_t objrock);
33  * ]|
34  * 
35  * Whenever the Glk library creates an object, it will call 
36  * <function>my_vm_reg_object&lpar;&rpar;</function>. It will pass the object
37  * pointer and the class number (from 0 to <inlineequation><mathphrase>N - 
38  * 1</mathphrase><alt>N - 1</alt></inlineequation>, where N is the value 
39  * returned by gidispatch_count_classes().)
40  * 
41  * You can return any value in the #gidispatch_rock_t object; the library will
42  * stash this away inside the object.
43  * 
44  * <note><para>
45  *   Note that this is entirely separate from the regular Glk rock, which is
46  *   always a #glui32 and can be set independently.
47  * </para></note>
48  * 
49  * Whenever the Glk library destroys an object, it will call
50  * <function>my_vm_unreg_object&lpar;&rpar;</function>. It passes you the object
51  * pointer, class number, and the object rock.
52  *
53  * One significant detail: It is possible that some Glk objects will already
54  * exist when your glk_main() function is called.
55  * 
56  * <note><para>
57  *   For example, MacGlk can open a stream when the user double-clicks a file;
58  *   this occurs before glk_main().
59  * </para></note>
60  * 
61  * So when you call gidispatch_set_object_registry(), it may immediately call
62  * your <function>my_vm_reg_object&lpar;&rpar;</function> callback, notifying 
63  * you of the existing objects. You must be prepared for this possibility.
64  * 
65  * <note><para>
66  *   If you are keeping hash tables, for example, create them before you call
67  *   gidispatch_set_object_registry().
68  * </para></note>
69  */
70 void 
71 gidispatch_set_object_registry(gidispatch_rock_t (*regi)(void *obj, glui32 objclass), void (*unregi)(void *obj, glui32 objclass, gidispatch_rock_t objrock))
72 {
73         ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
74         winid_t win;
75     strid_t str;
76     frefid_t fref;
77     
78     glk_data->register_obj = regi;
79     glk_data->unregister_obj = unregi;
80     
81     if(glk_data->register_obj) 
82         {
83         /* It's now necessary to go through all existing objects, and register them. */
84         for(win = glk_window_iterate(NULL, NULL); win; win = glk_window_iterate(win, NULL))
85             win->disprock = (*glk_data->register_obj)(win, gidisp_Class_Window);
86         for(str = glk_stream_iterate(NULL, NULL); str; str = glk_stream_iterate(str, NULL))
87             str->disprock = (*glk_data->register_obj)(str, gidisp_Class_Stream);
88         for(fref = glk_fileref_iterate(NULL, NULL); fref; fref = glk_fileref_iterate(fref, NULL))
89             fref->disprock = (*glk_data->register_obj)(fref, gidisp_Class_Fileref);
90     }
91 }
92
93 /**
94  * gidispatch_get_objrock:
95  * @obj: An opaque object.
96  * @objclass: One of #gidisp_Class_Window, #gidisp_Class_Stream,
97  * #gidisp_Class_Fileref, or #gidisp_Class_Schannel.
98  *
99  * You can, at any time, get the object rock of an object. The library
100  * implements this function.
101  * 
102  * With this and your two callbacks, you can maintain (say) a hash table for
103  * each object class, and easily convert back and forth between hash table keys
104  * and Glk object pointers. A more sophisticated run-time system (such as Java)
105  * could create a typed VM object for every Glk object, thus allowing VM code to
106  * manipulate Glk objects intelligently.
107  */
108 gidispatch_rock_t 
109 gidispatch_get_objrock(void *obj, glui32 objclass)
110 {
111         g_return_val_if_fail(obj, (gidispatch_rock_t)NULL);
112
113         
114         switch(objclass) 
115         {
116                 case gidisp_Class_Window:
117                         return ((winid_t)obj)->disprock;
118                 case gidisp_Class_Stream:
119                         return ((strid_t)obj)->disprock;
120                 case gidisp_Class_Fileref:
121                         return ((frefid_t)obj)->disprock;
122                 case gidisp_Class_Schannel:
123                         return ((schanid_t)obj)->disprock;
124                 default: 
125                 {
126                         gidispatch_rock_t dummy;
127                         dummy.num = 0;
128                         return dummy;
129                 }
130         }
131 }
132
133 /**
134  * gidispatch_set_retained_registry:
135  * @regi: Function to call whenever the Glk library assumes ownership of an
136  * array.
137  * @unregi: Function to call whenever the Glk library releases ownership of an
138  * array.
139  *
140  * A few Glk functions take an array and hold onto it. The memory is 
141  * <quote>owned</quote> by the library until some future Glk call releases it.
142  * While the library retains the array, your program should not read, write,
143  * move, or deallocate it. When the library releases it, the contents are in
144  * their final form, and you can copy them out (if appropriate) and dispose of
145  * the memory as you wish.
146  * 
147  * To allow this, the library implements gidispatch_set_retained_registry().
148  * 
149  * Again, you pass in two function pointers:
150  * |[
151  * gidispatch_rock_t my_vm_reg_array(void *array, glui32 len, char *typecode);
152  * void my_vm_unreg_array(void *array, glui32 len, char *typecode, gidispatch_rock_t objrock);
153  * ]|
154  *
155  * Whenever a Glk function retains an array, it will call 
156  * <function>my_vm_reg_array&lpar;&rpar;</function>. This occurs only if you 
157  * pass an array to an argument with the <code>"#!"</code> prefix.
158  *
159  * <note><para>
160  *   But not in every such case. Wait for the
161  *   <function>my_vm_reg_array&lpar;&rpar;</function> call to confirm it.
162  * </para></note>
163  *
164  * The library passes the array and its length, exactly as you put them in the
165  * #gluniversal_t array. It also passes the string which describes the argument.
166  *
167  * <note><para>
168  *   Currently, the only calls that retain arrays are glk_request_line_event(),
169  *   glk_stream_open_memory(), glk_request_line_event_uni(), and
170  *   glk_stream_open_memory_uni(). The first two of these use arrays of
171  *   characters, so the string is <code>"&+#!Cn"</code>. The latter two use
172  *   arrays of #glui32, so the string is <code>"&+#!Iu"</code>.
173  * </para></note>
174  * 
175  * You can return any value in the #gidispatch_rock_t object; the library will
176  * stash this away with the array.
177  * 
178  * When a Glk function releases a retained array, it will call
179  * <function>my_vm_unreg_array&lpar;&rpar;</function>. It passes back the same
180  * @array, @len, and @typecode parameters, as well as the #gidispatch_rock_t you
181  * returned from <function>my_vm_reg_array&lpar;&rpar;</function>.
182  * 
183  * With these callbacks, you can maintain a collection of retained arrays. You
184  * can use this to copy data from C arrays to your own data structures, or keep
185  * relocatable memory locked, or prevent a garbage-collection system from
186  * deallocating an array while Glk is writing to it.
187  */
188 void 
189 gidispatch_set_retained_registry(gidispatch_rock_t (*regi)(void *array, glui32 len, char *typecode), void (*unregi)(void *array, glui32 len, char *typecode, gidispatch_rock_t objrock))
190 {
191         ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
192         glk_data->register_arr = regi;
193         glk_data->unregister_arr = unregi;
194 }