From 5623908aeef70e5083f3b49986c7547ed044fedd Mon Sep 17 00:00:00 2001 From: Aaron Plattner Date: Wed, 28 Apr 2010 12:37:08 -0700 Subject: [PATCH] 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 Reviewed-by: Tiago Vignatti Signed-off-by: Keith Packard --- include/privates.h | 64 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 57 insertions(+), 7 deletions(-) diff --git a/include/privates.h b/include/privates.h index 3c5c32175..e6f788de1 100644 --- a/include/privates.h +++ b/include/privates.h @@ -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);