libpkgconf: update cache docs to new format

pull/100/head
William Pitcock 2016-12-10 19:40:51 -06:00
parent 74fbf4e5dc
commit 9efa991d98
3 changed files with 98 additions and 9 deletions

45
doc/libpkgconf-cache.rst Normal file
View File

@ -0,0 +1,45 @@
libpkgconf `cache` module
=========================
The libpkgconf `cache` module manages a package/module object cache, allowing it to
avoid loading duplicate copies of a package/module.
A cache is tied to a specific pkgconf client object, so package objects should not
be shared across threads.
.. c:function:: pkgconf_pkg_t *pkgconf_cache_lookup(const pkgconf_client_t *client, const char *id)
Looks up a package in the cache given an `id` atom,
such as ``gtk+-3.0`` and returns the already loaded version
if present.
:param pkgconf_client_t* client: The client object to access.
:param char* id: The package atom to look up in the client object's cache.
:return: A package object if present, else ``NULL``.
:rtype: pkgconf_pkg_t *
.. c:function:: void pkgconf_cache_add(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
Adds an entry for the package to the package cache.
The cache entry must be removed if the package is freed.
:param pkgconf_client_t* client: The client object to modify.
:param pkgconf_pkg_t* pkg: The package object to add to the client object's cache.
:return: nothing
.. c:function:: void pkgconf_cache_remove(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
Deletes a package from the client object's package cache.
:param pkgconf_client_t* client: The client object to modify.
:param pkgconf_pkg_t* pkg: The package object to remove from the client object's cache.
:return: nothing
.. c:function:: void pkgconf_cache_free(pkgconf_client_t *client)
Releases all resources related to a client object's package cache.
This function should only be called to clear a client object's package cache,
as it may release any package in the cache.
:param pkgconf_client_t* client: The client object to modify.

View File

@ -6,4 +6,5 @@ libpkgconf - an API for managing `pkg-config` modules
libpkgconf-argvsplit libpkgconf-argvsplit
libpkgconf-audit libpkgconf-audit
libpkgconf-cache
libpkgconf-client libpkgconf-client

View File

@ -16,11 +16,31 @@
#include <libpkgconf/libpkgconf.h> #include <libpkgconf/libpkgconf.h>
/* /*
* pkgconf_cache_lookup(id) * !doc
* *
* looks up a package in the cache given an 'id' atom, * libpkgconf `cache` module
* such as 'gtk+-3.0' and returns the already loaded version * =========================
*
* The libpkgconf `cache` module manages a package/module object cache, allowing it to
* avoid loading duplicate copies of a package/module.
*
* A cache is tied to a specific pkgconf client object, so package objects should not
* be shared across threads.
*/
/*
* !doc
*
* .. c:function:: pkgconf_pkg_t *pkgconf_cache_lookup(const pkgconf_client_t *client, const char *id)
*
* Looks up a package in the cache given an `id` atom,
* such as ``gtk+-3.0`` and returns the already loaded version
* if present. * if present.
*
* :param pkgconf_client_t* client: The client object to access.
* :param char* id: The package atom to look up in the client object's cache.
* :return: A package object if present, else ``NULL``.
* :rtype: pkgconf_pkg_t *
*/ */
pkgconf_pkg_t * pkgconf_pkg_t *
pkgconf_cache_lookup(const pkgconf_client_t *client, const char *id) pkgconf_cache_lookup(const pkgconf_client_t *client, const char *id)
@ -39,10 +59,16 @@ pkgconf_cache_lookup(const pkgconf_client_t *client, const char *id)
} }
/* /*
* pkgconf_cache_add(pkg) * !doc
* *
* adds an entry for the package to the package cache. * .. c:function:: void pkgconf_cache_add(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
* the cache entry must be removed if the package is freed. *
* Adds an entry for the package to the package cache.
* The cache entry must be removed if the package is freed.
*
* :param pkgconf_client_t* client: The client object to modify.
* :param pkgconf_pkg_t* pkg: The package object to add to the client object's cache.
* :return: nothing
*/ */
void void
pkgconf_cache_add(pkgconf_client_t *client, pkgconf_pkg_t *pkg) pkgconf_cache_add(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
@ -55,9 +81,15 @@ pkgconf_cache_add(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
} }
/* /*
* pkgconf_cache_remove(pkg) * !doc
* *
* deletes a package from the cache entry. * .. c:function:: void pkgconf_cache_remove(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
*
* Deletes a package from the client object's package cache.
*
* :param pkgconf_client_t* client: The client object to modify.
* :param pkgconf_pkg_t* pkg: The package object to remove from the client object's cache.
* :return: nothing
*/ */
void void
pkgconf_cache_remove(pkgconf_client_t *client, pkgconf_pkg_t *pkg) pkgconf_cache_remove(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
@ -68,6 +100,17 @@ pkgconf_cache_remove(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
pkgconf_node_delete(&pkg->cache_iter, &client->pkg_cache); pkgconf_node_delete(&pkg->cache_iter, &client->pkg_cache);
} }
/*
* !doc
*
* .. c:function:: void pkgconf_cache_free(pkgconf_client_t *client)
*
* Releases all resources related to a client object's package cache.
* This function should only be called to clear a client object's package cache,
* as it may release any package in the cache.
*
* :param pkgconf_client_t* client: The client object to modify.
*/
void void
pkgconf_cache_free(pkgconf_client_t *client) pkgconf_cache_free(pkgconf_client_t *client)
{ {