git.roojs.org Git - gnome.gobject-introspection/blob - docs/metadata-annotations-proposal.txt

   1 ***FIXME****
   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 :\
   8 ***FIXME****
   9
  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.
  17
  18
  19 Typed annotations:
  20
  21 struct AnnotationBlob
  22 {
  23   guint32 entry_offset;
  24   guint32 type;
  25   guint32 values_offset;
  26 };
  27
  28 entry_offset:   offset of metadata entry (must be valid target for this
  29                 annotation) described by this annotation
  30
  31 type:           offset of AttributeBlob describing type of this annotation
  32
  33 values_offset:  offset to n_fields (read from corresponding AttributeBlob)
  34                 values of appropriate types, specifying value of this
  35                 annotation
  36
  37
  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
  41                 ConstantBlobs.
  42
  43
  44 typedef enum
  45 {
  46   function = 1 << 0,
  47   type     = 1 << 1,
  48   param    = 1 << 2,
  49   value    = 1 << 3,
  50   signal   = 1 << 4,
  51   property = 1 << 5,
  52
  53   all      = 0x3F,
  54 } AttributeTargets;
  55
  56
  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)
  63
  64
  65 struct AttributeBlob
  66 {
  67   guint16               blob_type;    /* 11 */
  68   guint                 deprecated      : 1;
  69   guint                 allow_multiple  : 1;
  70   AttributeTargets      targets         : 6;
  71   guint                 has_constructor : 1;
  72   guint                 reserved        : 8;
  73   guint32               name;
  74
  75   GTypeBlob             gtype;
  76   guint32               constructor;
  77   guint16               n_fields;
  78   FieldBlob             fields[];
  79 };
  80
  81 allow_multiple: if that attribute can be applied multiple times to one
  82                 annotated entry.
  83
  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
  88                 property.
  89
  90 has_constructor: if that attribute has constructor. If 0, default constructor
  91                  is used.
  92
  93 name:           name of this attribute.
  94
  95 gtype:          GType under which is the attribute registered.
  96
  97
  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 ?
 101
 102
 103 constructor:    offset to constructor function for this attribute, or 0 if
 104                 default is used.
 105
 106
 107                 mclasen: This is unclear. Who uses this constructor, and
 108                 what is it used for ?
 109
 110
 111 n_fields:       number of fields this attribute has
 112
 113
 114                 mclasen: it seems to me that, since we have struct support,
 115                 a single field would be sufficient.
 116
 117
 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:
 121                  void
 122                  boolean
 123                  int8
 124                  uint8
 125                  int16
 126                  uint16
 127                  int32
 128                  uint32
 129                  int64
 130                  uint64
 131                  int
 132                  uint
 133                  long
 134                  ulong
 135                  ssize_t
 136                  size_t
 137                  float
 138                  double
 139                  utf8
 140                  filename
 141                  type
 142
 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.
 153
 154
 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
 159                 as { 2, 6 }
 160
 161
 162                 For example, Python might use the following syntax:
 163
 164                 gobject.annotation(my_container, ContainerTypeAttribute,
 165                                    type=gobject.GObject)
 166
 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?).
 174
 175                 The same expressed in C could look as follows:
 176
 177                 G_OBJECT_ANNOTATION(my_container_constant, ContainerTypeAttribute
 178                                     "type", "GObject.GObject")
 179
 180                 where G_OBJECT_ANNOTATION is hypothetical macro used for marking
 181                 annotations for metadata scanner.