2 Currently annotations are required to be pooled in one place,
3 sorted by entry offset. That makes it impossible to add annotations
4 in incremental manner, making it impossible for dynamic languages
5 like Python to give correct metadata. We should probably remove that
6 requirement, and add offset to annotations to each annotatable entry,
7 this however means 4*n more bytes used :\
10 mclasen: Incremental generation of metadata is already
11 problematic without annotations, since you have to grow the
12 directory, and we currently assume that local entries
13 are before remote entries in the directory.
14 Adding 4 bytes to each type, value and arg blob is certainly
15 going to blow the size of the metadata up unreasonably,
16 since these are the most common blob types.
25 guint32 values_offset;
28 entry_offset: offset of metadata entry (must be valid target for this
29 annotation) described by this annotation
31 type: offset of AttributeBlob describing type of this annotation
33 values_offset: offset to n_fields (read from corresponding AttributeBlob)
34 values of appropriate types, specifying value of this
38 mclasen: What type of blob is being pointed to here ?
39 ValueBlob only holds integer types (for use in enums).
40 For general types, you will probably have to use
57 mclasen: Does "all" mean just all of the above, or
58 any blob ? Whats the rationale for not allowing annotations
59 on some blob types ? Wouldn't it be better to specify
60 the attribut target using the blob type enum (no way to
61 specify a subset of targets then, but we could still
62 indicate "all", e.g. as 0)
67 guint16 blob_type; /* 11 */
69 guint allow_multiple : 1;
70 AttributeTargets targets : 6;
71 guint has_constructor : 1;
81 allow_multiple: if that attribute can be applied multiple times to one
84 targets: bitmask of allowed targets for annotation with this attribute.
85 Possible targets are: function (including methods), function
86 parameter, type (that is, object, enum, or interface), value
87 (constant or variable exposed from metadata), signal or
90 has_constructor: if that attribute has constructor. If 0, default constructor
93 name: name of this attribute.
95 gtype: GType under which is the attribute registered.
98 mclasen: This is unclear. Why would attributes be registered
99 in GType ? Do we have a special base type for them ? Do
100 they need to conform to some interface ?
103 constructor: offset to constructor function for this attribute, or 0 if
107 mclasen: This is unclear. Who uses this constructor, and
108 what is it used for ?
111 n_fields: number of fields this attribute has
114 mclasen: it seems to me that, since we have struct support,
115 a single field would be sufficient.
118 fields: array of SimpleTypeBlobs describing fields this attribute has.
119 Only allowed are types for which valid literals exist. Currently
120 that's the following types:
143 "type" is guint32 specifying offset to another metadata
144 entry describing one of: object, interface, enum, function
145 (including methods), callback, signal or constant. "type"
146 literals should be exposed to the user either as strings
147 specyfing fully qualified name of one of above types,
148 mangled according to rules of language used (if the language
149 uses any mangling of type names), or type expressed as
150 valid type literal in syntax of language.
151 Implementation is responsible for reading such type name and
152 converting it to correct guint32 value.
155 mclasen: I would be pragmatic and specify types just be
156 a qualified name, as you already do in your C example below.
157 But I think there is a case for allowing arrays of basic
158 types. I could imagine storing the "Since: 2.6" annotation
162 For example, Python might use the following syntax:
164 gobject.annotation(my_container, ContainerTypeAttribute,
165 type=gobject.GObject)
167 Here, my_container is variable of some container class,
168 ContainerTypeAttribute is hypothetical attribute specifying
169 specialisation for containers, and type=gobject.GObject says
170 that this given container will hold GObjects. Python
171 implementation is now responsible for converting gobject.GObject
172 into guint32 value pointing to definition of GObject (***FIXME***
173 how do we deal with GObject which is fundamental type?).
175 The same expressed in C could look as follows:
177 G_OBJECT_ANNOTATION(my_container_constant, ContainerTypeAttribute
178 "type", "GObject.GObject")
180 where G_OBJECT_ANNOTATION is hypothetical macro used for marking
181 annotations for metadata scanner.