dix: Improve documentation of the DIX private data functions.
The functions exported by the devPrivates code were poorly documented. I tried to spruce it up a little. Signed-off-by: Aaron Plattner <aplattner@nvidia.com> Reviewed-by: Tiago Vignatti <tiago.vignatti@nokia.com> Signed-off-by: Keith Packard <keithp@keithp.com>
This commit is contained in:
parent
986d46144b
commit
5623908aee
|
@ -24,32 +24,71 @@ struct _Private;
|
|||
typedef struct _Private PrivateRec;
|
||||
|
||||
/*
|
||||
* Request pre-allocated private space for your driver/module.
|
||||
* Calling this is not necessary if only a pointer by itself is needed.
|
||||
* Request pre-allocated private space for your driver/module. This function
|
||||
* increases the amount of space allocated automatically when dixLookupPrivate
|
||||
* is called on a PrivateRec that does not yet have a value associated with
|
||||
* 'key'.
|
||||
*
|
||||
* This function will only increase the reserved size: if a size was previously
|
||||
* requested, then dixRequestPrivate causes later calls to dixLookupPrivate to
|
||||
* allocate the maximum of the old size and 'size'. Requested sizes are reset
|
||||
* to 0 by dixResetPrivates, which is called before each server generation.
|
||||
*
|
||||
* If dixRequestPrivate is not called with a nonzero size for 'key', then the
|
||||
* module responsible for 'key' must manage the associated pointer itself with
|
||||
* dixSetPrivate.
|
||||
*
|
||||
* dixRequestPrivate returns FALSE if it cannot store the requested size.
|
||||
*/
|
||||
extern _X_EXPORT int
|
||||
dixRequestPrivate(const DevPrivateKey key, unsigned size);
|
||||
|
||||
/*
|
||||
* Allocates a new private and attaches it to an existing object.
|
||||
* Allocates space for an association of 'key' with a value in 'privates'.
|
||||
*
|
||||
* If a nonzero size was requested with dixRequestPrivate, then
|
||||
* dixAllocatePrivate also allocates the requested amount of memory and
|
||||
* associates the pointer to that memory with 'key' in 'privates'. The
|
||||
* allocated memory is initialized to zero. This memory can only be freed by
|
||||
* dixFreePrivates.
|
||||
*
|
||||
* If dixRequestPrivate was never called with a nonzero size, then
|
||||
* dixAllocatePrivate associates NULL with 'key' in 'privates'.
|
||||
*
|
||||
* dixAllocatePrivate returns a pointer to the value associated with 'key' in
|
||||
* 'privates', unless a memory allocation fails, in which case it returns NULL.
|
||||
*/
|
||||
extern _X_EXPORT pointer *
|
||||
dixAllocatePrivate(PrivateRec **privates, const DevPrivateKey key);
|
||||
|
||||
/*
|
||||
* Look up a private pointer.
|
||||
*
|
||||
* If no value is currently associated with 'key' in 'privates', then
|
||||
* dixLookupPrivate calls dixAllocatePrivate and returns the resulting
|
||||
* associated value.
|
||||
*
|
||||
* dixLookupPrivate returns NULL if a memory allocation fails.
|
||||
*/
|
||||
extern _X_EXPORT pointer
|
||||
dixLookupPrivate(PrivateRec **privates, const DevPrivateKey key);
|
||||
|
||||
/*
|
||||
* Look up the address of a private pointer.
|
||||
* Look up the address of a private pointer. If 'key' is not associated with a
|
||||
* value in 'privates', then dixLookupPrivateAddr calls dixAllocatePrivate and
|
||||
* returns a pointer to the resulting associated value.
|
||||
*
|
||||
* dixLookupPrivateAddr returns NULL if 'key' was not previously associated in
|
||||
* 'privates' and a memory allocation fails.
|
||||
*/
|
||||
extern _X_EXPORT pointer *
|
||||
dixLookupPrivateAddr(PrivateRec **privates, const DevPrivateKey key);
|
||||
|
||||
/*
|
||||
* Set a private pointer.
|
||||
* Associate 'val' with 'key' in 'privates' so that later calls to
|
||||
* dixLookupPrivate(privates, key) will return 'val'.
|
||||
*
|
||||
* dixSetPrivate returns FALSE if a memory allocation fails.
|
||||
*/
|
||||
extern _X_EXPORT int
|
||||
dixSetPrivate(PrivateRec **privates, const DevPrivateKey key, pointer val);
|
||||
|
@ -63,22 +102,33 @@ typedef struct _PrivateCallback {
|
|||
pointer *value; /* address of private pointer */
|
||||
} PrivateCallbackRec;
|
||||
|
||||
/*
|
||||
* Register a function to be called when dixAllocPrivate successfully associates
|
||||
* 'key' with a new PrivateRec.
|
||||
*/
|
||||
extern _X_EXPORT int
|
||||
dixRegisterPrivateInitFunc(const DevPrivateKey key,
|
||||
CallbackProcPtr callback, pointer userdata);
|
||||
|
||||
/*
|
||||
* Register a function to be called when dixFreePrivates unassociates 'key' with
|
||||
* a PrivateRec.
|
||||
*/
|
||||
extern _X_EXPORT int
|
||||
dixRegisterPrivateDeleteFunc(const DevPrivateKey key,
|
||||
CallbackProcPtr callback, pointer userdata);
|
||||
|
||||
/*
|
||||
* Frees private data.
|
||||
* Unassociates all keys from 'privates', calls the callbacks registered with
|
||||
* dixRegisterPrivateDeleteFunc, and frees all private data automatically
|
||||
* allocated via dixRequestPrivate.
|
||||
*/
|
||||
extern _X_EXPORT void
|
||||
dixFreePrivates(PrivateRec *privates);
|
||||
|
||||
/*
|
||||
* Resets the subsystem, called from the main loop.
|
||||
* Resets the privates subsystem. dixResetPrivates is called from the main loop
|
||||
* before each server generation. This function must only be called by main().
|
||||
*/
|
||||
extern _X_EXPORT int
|
||||
dixResetPrivates(void);
|
||||
|
|
Loading…
Reference in New Issue
Block a user