diff --git a/doc/xml/Xserver-spec.xml b/doc/xml/Xserver-spec.xml index 466b79d40..c5fd19175 100644 --- a/doc/xml/Xserver-spec.xml +++ b/doc/xml/Xserver-spec.xml @@ -92,6 +92,13 @@ efw Revised for devPrivates changes + + 3.5 + July 2010 + ac + Revised for Xorg 1.9 devPrivates changes + and 1.8 CreateNewResourceType changes + Copyright © 1994 X Consortium, Inc., 2004 X.org Foundation, Inc. @@ -4808,32 +4815,68 @@ Two new extensibility concepts have been developed for release 4, Wrappers and devPrivates. These replace the R3 GCInterest queues, which were not a general enough mechanism for many extensions and only provided hooks into a single data structure. devPrivates have been revised substantially for -X.org X server relase 1.5. +X.Org X server release 1.5, and updated again for the 1.9 release.
devPrivates devPrivates provides a way to attach arbitrary private data to various server structures. Any structure which contains a devPrivates field of -type PrivateRec supports this mechanism. Private data can be allocated at -any time during an object's life cycle and callbacks are available to initialize and clean -up allocated space. +type PrivateRec supports this mechanism. Some structures allow +allocating space for private data after some objects have been created, others +require all space allocations be registered before any objects of that type +are created. Xserver/include/privates.h +lists which of these cases applies to each structure containing +devPrivates. + + +To request private space, use +
+ Bool dixRegisterPrivateKey(DevPrivateKey key, DevPrivateType type, unsigned size); +
+The first argument is a pointer to a DevPrivateKeyRec which +will serve as the unique identifier for the private data. Typically this is +the address of a static DevPrivateKeyRec in your code. +The second argument is the class of objects for which this key will apply. +The third argument is the size of the space being requested, or +0 to only allocate a pointer that the caller will manage. +If space is requested, this space will be automatically freed when the object +is destroyed. Note that a call to dixSetPrivate +that changes the pointer value may cause the space to be unreachable by the caller, however it will still be automatically freed. +The function returns TRUE unless memory allocation fails. +If the function is called more than once on the same key, all calls must use +the same value for size or the server will abort. + + +To request private space and have the server manage the key, use +
+ DevPrivateKey dixCreatePrivateKey(DevPrivateType type, unsigned size); +
+The type and size arguments are +the same as those to dixRegisterPrivateKey but this +function allocates a DevPrivateKeyRec and returns a pointer to it +instead of requiring the caller to pass a pointer to an existing structure. +The server will free it automatically when the privates system is restarted +at server reset time. + To attach a piece of private data to an object, use:
- int dixSetPrivate(PrivateRec **privates, const DevPrivateKey key, pointer val) + void dixSetPrivate(PrivateRec **privates, const DevPrivateKey key, pointer val)
-The first argument is the address of the devPrivates field -in the target structure. This field is managed privately by the DIX layer and -should not be directly modified. The second argument is some address value which -will serve as the unique identifier for the private data. Typically this is the address -of some global variable in your code. Only one piece of data with a given key can be attached to an object. However, you -can use the same key to store data in any object that supports the devPrivates mechanism. The third -argument is the value to store. +The first argument is the address of the devPrivates +field in the target structure. This field is managed privately by the DIX +layer and should not be directly modified. The second argument is a pointer +to the DevPrivateKeyRec which you registered with +dixRegisterPrivateKey or allocated with +dixCreatePrivateKey. Only one +piece of data with a given key can be attached to an object, and in most cases +each key is specific to the type of object it was registered for. (An +exception is the PRIVATE_XSELINUX class which applies to multiple object types.) +The third argument is the value to store. -If private data with the given key is already associated with the object, dixSetPrivate will -overwrite the old value with the new one. Otherwise, new space will be allocated to hold the pointer value. -The function returns TRUE unless memory allocation fails, but note that since memory allocation only -occurs on the first reference to the private data, all subsequent calls are guaranteed to succeed. +If private data with the given key is already associated with the object, +dixSetPrivate will overwrite the old value with the +new one. To look up a piece of private data, use one of: @@ -4842,56 +4885,22 @@ To look up a piece of private data, use one of: pointer *dixLookupPrivateAddr(PrivateRec **privates, const DevPrivateKey key) The first argument is the address of the devPrivates field -in the target structure. The second argument is the key to look up. If private data with the given key is already associated -with the object, dixLookupPrivate will return the stored pointer value while dixLookupPrivateAddr -will return the address of the stored pointer. Otherwise, new space will be first allocated to hold the pointer value -and it will be initialized to NULL. Both functions return NULL if memory allocation fails, but note that -since memory allocation only occurs on the first reference to the private data, all subsequent calls are guaranteed to succeed. +in the target structure. The second argument is the key to look up. +If a non-zero size was given when the key was registered, or if private data +with the given key is already associated with the object, then +dixLookupPrivate will return the pointer value +while dixLookupPrivateAddr +will return the address of the pointer. -To request pre-allocated private space, use -
- int dixRequestPrivate(const DevPrivateKey key, unsigned size) -
-The first argument is the key for which space is being requested. The second argument is the size of the space being requested. -After this function has been called, -future calls to dixLookupPrivate or dixLookupPrivateAddr that cause the private pointer -to be initially allocated will also allocate size bytes of space cleared to zero and initialize the private pointer to point -to this space instead of NULL. This space will be automatically freed. Note that a call to dixSetPrivate -that changes the pointer value may cause the space to be unreachable by the caller, however it will still be automatically freed. -The function returns TRUE unless memory allocation fails. If the function is called more than once, the largest value -of size is used. - - -To set callbacks for initializing and cleaning up private space, use -
- typedef struct { - DevPrivateKey key; - pointer *value; - } PrivateCallbackRec; - - int dixRegisterPrivateInitFunc(const DevPrivateKey key, - CallbackProcPtr callback, - pointer userdata) - int dixRegisterPrivateDeleteFunc(const DevPrivateKey key, - CallbackProcPtr callback, - pointer userdata) -
-The first argument is the key for which the callbacks are being registered. The second argument is the callback function. The third argument -will be passed as the user data argument to the callback function when it is called. The call data argument to the callback is a pointer to -a structure of type PrivateCallbackRec. - -The init callback is called immediately after new private space has been allocated for the given key. The delete callback is called immediately -before the private space is freed when the object is being destroyed. The PrivateCallbackRec structure contains the devPrivate key -and the address of the private pointer. The init callback may be used to initialize any pre-allocated space requested by -dixRequestPrivate, while the delete callback may be used to free any data stored there. However the callbacks are called even -if no pre-allocated space was requested. - - -When implementing new server resource objects that support devPrivates, there are three steps to perform: -Declare a field of type PrivateRec * in your structure; +When implementing new server resource objects that support devPrivates, there +are four steps to perform: +Add a type value to the DevPrivateType enum in +Xserver/include/privates.h, +declare a field of type PrivateRec * in your structure; initialize this field to NULL when creating any objects; and -call the dixFreePrivates function, passing in the field value, when freeing any objects. +when freeing any objects call the dixFreePrivates or +dixFreeObjectWithPrivates function.
Wrappers