1ggGetScope(3) GGI ggGetScope(3)
2
6 ggGetScope, ggFromScope, ggDelScope, ggNewScope : Portable code module
7 loading facilities
8
10 #include <ggi/gg.h>
11 gg_scope ggGetScope(const char *location);
13 void ggDelScope(gg_scope scope);
15 void *ggFromScope(gg_scope, const char *symbol);
17 typedef void *(*ggfunc_scope_get)(void * handle, const char * symbol);
19 typedef void (*ggfunc_scope_del)(void * handle);
20 gg_scope ggNewScope(const char * location, void * handle,
22 ggfunc_scope_get get, ggfunc_scope_del del)
23
26 LibGG abstracts dynamic code loading (and emulates dynamic code loading
27 for statically linked embedded binaries) through a simple API which
28 represents the very lowest level required of any loadable module sys‐
29 tem. The actual underlying mechanisms used in various operating sys‐
30 tems to load additional code into an application on demand vary drasti‐
31 cally, however, minus OS-specific frills, they can all be mapped to the
32 above three LibGG API functions.
33 ggGetScope finds a loadable collection of symbols known by its location
35 through whatever system is available on the operating system. Those
36 symbols were once supposed to be code from modules, but the scope
37 abstraction does not impose this restriction. The scopes can have dif‐
38 ferent implementations and are not restricted to dynamic libraries.
39 They could also be used as an interface to a attribute/value configura‐
40 tion system.
41 Note that when a scope happens to be dynamic library, the symbols are
43 loaded into the address space of the caller, but libgg does not guaran‐
44 tee that the imported symbols will be seen by other modules.
45 ggDelScope unloads the symbol collection represented by the handle
47 scope, which must have been previously loaded with ggGetScope (scope
48 should be a return value from a previous call to ggGetScope.) Refer‐
49 ence counts are kept to ensure that redundantly loaded symbol collec‐
50 tions are not discarded until their last owner releases them. Calling
51 ggDelScope on a handle too many times, or on an invalid handle, may
52 produce undefined results. Accessing symbols after the collections
53 they were contained in are unloaded will produce undesirable and unde‐
54 fined results.
55 ggFromScope searches the symbol collection represented by the handle
57 scope, which has been loaded with ggGetScope (and not yet unloaded with
58 ggDelScope, of course) for a symbol named symbol, so that the applica‐
59 tion may use the item associated with the symbol. The parameter scope
60 should be a return value from a previous call to ggDelScope. As
61 ggFromScope may have no way of knowing what the symbol represents, the
62 application must take the responsibility for assigning the item a cor‐
63 rect C type.
64 ggNewScope allows to register a custom scope to libgg. The primary pur‐
66 pose is to allow libraries to provide builtin modules that are accessi‐
67 ble through the same interface as dynamic ones. location is the string
68 at which the scope can be retreived. handle is a opaque pointer pro‐
69 vided by the caller that will be passed to the callbacks. get is a
70 function that take an opaque handle, a symbol name, and that must
71 return the requested symbol address, or NULL if not found. del is a
72 function that will take the provided handler, and that must cleanup
73 everything before the scope is removed from the scope registry. This
74 scheme allows to implement all kind of scopes in a very flexible way.
75 Note that ggNewScope will take a reference on the scope.
76
78 On success, ggGetScope returns an opaque pointer to a handle represent‐
79 ing a newly loaded symbol collection (which must be retained in order
80 to use or free the collection.) These pointers are not guaranteed to
81 be unique. On failure, ggGetScope returns NULL.
82 ggFromScope returns the address of the item that the named symbol rep‐
84 resents, if it has been loaded into the caller's address space. Other‐
85 wise it returns NULL. Note that the value associated to a symbol really
86 depends on the scope itself and the caller must know what is behind it.
87 So a NULL value does not necessarily means failure. It could be a valid
88 value for a specific scope.
89 ggNewScope returns an opaque pointer to a handle representing the cus‐
91 tom scope. On failure, ggNewScope returns NULL.
92libgg-1.0.x 2005-08-26 ggGetScope(3)