aboutsummaryrefslogtreecommitdiff
path: root/xorg-server/include/privates.h
diff options
context:
space:
mode:
Diffstat (limited to 'xorg-server/include/privates.h')
-rw-r--r--xorg-server/include/privates.h64
1 files changed, 57 insertions, 7 deletions
diff --git a/xorg-server/include/privates.h b/xorg-server/include/privates.h
index 3c5c32175..e6f788de1 100644
--- a/xorg-server/include/privates.h
+++ b/xorg-server/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);