libpkgconf: document queue module

pull/100/head
William Pitcock 2016-12-10 23:27:21 -06:00
parent 4cc0d017da
commit 4967c85d49
3 changed files with 138 additions and 0 deletions

59
doc/libpkgconf-queue.rst Normal file
View File

@ -0,0 +1,59 @@
libpkgconf `queue` module
=========================
The `queue` module provides an interface that allows easily building a dependency graph from an
arbitrary set of dependencies. It also provides support for doing "preflight" checks on the entire
dependency graph prior to working with it.
Using the `queue` module functions is the recommended way of working with dependency graphs.
.. c:function:: void pkgconf_queue_push(pkgconf_list_t *list, const char *package)
Pushes a requested dependency onto the dependency resolver's queue.
:param pkgconf_list_t* list: the dependency resolution queue to add the package request to.
:param char* package: the dependency atom requested
:return: nothing
.. c:function:: bool pkgconf_queue_compile(pkgconf_client_t *client, pkgconf_pkg_t *world, pkgconf_list_t *list)
Compile a dependency resolution queue into a dependency resolution problem if possible, otherwise report an error.
:param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
:param pkgconf_pkg_t* world: The designated root of the dependency graph.
:param pkgconf_list_t* list: The list of dependency requests to consider.
:return: true if the built dependency resolution problem is consistent, else false
:rtype: bool
.. c:function:: void pkgconf_queue_free(pkgconf_list_t *list)
Release any memory related to a dependency resolution queue.
:param pkgconf_list_t* list: The dependency resolution queue to release.
:return: nothing
.. c:function:: void pkgconf_queue_apply(pkgconf_client_t *client, pkgconf_list_t *list, pkgconf_queue_apply_func_t func, int maxdepth, unsigned int flags, void *data)
Attempt to compile a dependency resolution queue into a dependency resolution problem, then attempt to solve the problem and
feed the solution to a callback function if a complete dependency graph is found.
:param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
:param pkgconf_list_t* list: The list of dependency requests to consider.
:param pkgconf_queue_apply_func_t func: The callback function to call if a solution is found by the dependency resolver.
:param int maxdepth: The maximum allowed depth for the dependency resolver. A depth of -1 means unlimited.
:param uint flags: A bitfield of flags that is passed to the dependency resolver, optionally modifying it's behaviour.
:param void* data: An opaque pointer which is passed to the callback function.
:returns: true if the dependency resolver found a solution, otherwise false.
:rtype: bool
.. c:function:: void pkgconf_queue_validate(pkgconf_client_t *client, pkgconf_list_t *list, pkgconf_queue_apply_func_t func, int maxdepth, unsigned int flags, void *data)
Attempt to compile a dependency resolution queue into a dependency resolution problem, then attempt to solve the problem.
:param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
:param pkgconf_list_t* list: The list of dependency requests to consider.
:param int maxdepth: The maximum allowed depth for the dependency resolver. A depth of -1 means unlimited.
:param uint flags: A bitfield of flags that is passed to the dependency resolver, optionally modifying it's behaviour.
:returns: true if the dependency resolver found a solution, otherwise false.
:rtype: bool

View File

@ -10,3 +10,4 @@ libpkgconf - an API for managing `pkg-config` modules
libpkgconf-client libpkgconf-client
libpkgconf-dependency libpkgconf-dependency
libpkgconf-path libpkgconf-path
libpkgconf-queue

View File

@ -15,11 +15,35 @@
#include <libpkgconf/libpkgconf.h> #include <libpkgconf/libpkgconf.h>
/*
* !doc
*
* libpkgconf `queue` module
* =========================
*
* The `queue` module provides an interface that allows easily building a dependency graph from an
* arbitrary set of dependencies. It also provides support for doing "preflight" checks on the entire
* dependency graph prior to working with it.
*
* Using the `queue` module functions is the recommended way of working with dependency graphs.
*/
typedef struct { typedef struct {
pkgconf_node_t iter; pkgconf_node_t iter;
char *package; char *package;
} pkgconf_queue_t; } pkgconf_queue_t;
/*
* !doc
*
* .. c:function:: void pkgconf_queue_push(pkgconf_list_t *list, const char *package)
*
* Pushes a requested dependency onto the dependency resolver's queue.
*
* :param pkgconf_list_t* list: the dependency resolution queue to add the package request to.
* :param char* package: the dependency atom requested
* :return: nothing
*/
void void
pkgconf_queue_push(pkgconf_list_t *list, const char *package) pkgconf_queue_push(pkgconf_list_t *list, const char *package)
{ {
@ -29,6 +53,19 @@ pkgconf_queue_push(pkgconf_list_t *list, const char *package)
pkgconf_node_insert_tail(&pkgq->iter, pkgq, list); pkgconf_node_insert_tail(&pkgq->iter, pkgq, list);
} }
/*
* !doc
*
* .. c:function:: bool pkgconf_queue_compile(pkgconf_client_t *client, pkgconf_pkg_t *world, pkgconf_list_t *list)
*
* Compile a dependency resolution queue into a dependency resolution problem if possible, otherwise report an error.
*
* :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
* :param pkgconf_pkg_t* world: The designated root of the dependency graph.
* :param pkgconf_list_t* list: The list of dependency requests to consider.
* :return: true if the built dependency resolution problem is consistent, else false
* :rtype: bool
*/
bool bool
pkgconf_queue_compile(pkgconf_client_t *client, pkgconf_pkg_t *world, pkgconf_list_t *list) pkgconf_queue_compile(pkgconf_client_t *client, pkgconf_pkg_t *world, pkgconf_list_t *list)
{ {
@ -45,6 +82,16 @@ pkgconf_queue_compile(pkgconf_client_t *client, pkgconf_pkg_t *world, pkgconf_li
return (world->requires.head != NULL); return (world->requires.head != NULL);
} }
/*
* !doc
*
* .. c:function:: void pkgconf_queue_free(pkgconf_list_t *list)
*
* Release any memory related to a dependency resolution queue.
*
* :param pkgconf_list_t* list: The dependency resolution queue to release.
* :return: nothing
*/
void void
pkgconf_queue_free(pkgconf_list_t *list) pkgconf_queue_free(pkgconf_list_t *list)
{ {
@ -68,6 +115,23 @@ pkgconf_queue_verify(pkgconf_client_t *client, pkgconf_pkg_t *world, pkgconf_lis
return pkgconf_pkg_verify_graph(client, world, maxdepth, flags); return pkgconf_pkg_verify_graph(client, world, maxdepth, flags);
} }
/*
* !doc
*
* .. c:function:: void pkgconf_queue_apply(pkgconf_client_t *client, pkgconf_list_t *list, pkgconf_queue_apply_func_t func, int maxdepth, unsigned int flags, void *data)
*
* Attempt to compile a dependency resolution queue into a dependency resolution problem, then attempt to solve the problem and
* feed the solution to a callback function if a complete dependency graph is found.
*
* :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
* :param pkgconf_list_t* list: The list of dependency requests to consider.
* :param pkgconf_queue_apply_func_t func: The callback function to call if a solution is found by the dependency resolver.
* :param int maxdepth: The maximum allowed depth for the dependency resolver. A depth of -1 means unlimited.
* :param uint flags: A bitfield of flags that is passed to the dependency resolver, optionally modifying it's behaviour.
* :param void* data: An opaque pointer which is passed to the callback function.
* :returns: true if the dependency resolver found a solution, otherwise false.
* :rtype: bool
*/
bool bool
pkgconf_queue_apply(pkgconf_client_t *client, pkgconf_list_t *list, pkgconf_queue_apply_func_t func, int maxdepth, unsigned int flags, void *data) pkgconf_queue_apply(pkgconf_client_t *client, pkgconf_list_t *list, pkgconf_queue_apply_func_t func, int maxdepth, unsigned int flags, void *data)
{ {
@ -95,6 +159,20 @@ pkgconf_queue_apply(pkgconf_client_t *client, pkgconf_list_t *list, pkgconf_queu
return true; return true;
} }
/*
* !doc
*
* .. c:function:: void pkgconf_queue_validate(pkgconf_client_t *client, pkgconf_list_t *list, pkgconf_queue_apply_func_t func, int maxdepth, unsigned int flags, void *data)
*
* Attempt to compile a dependency resolution queue into a dependency resolution problem, then attempt to solve the problem.
*
* :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
* :param pkgconf_list_t* list: The list of dependency requests to consider.
* :param int maxdepth: The maximum allowed depth for the dependency resolver. A depth of -1 means unlimited.
* :param uint flags: A bitfield of flags that is passed to the dependency resolver, optionally modifying it's behaviour.
* :returns: true if the dependency resolver found a solution, otherwise false.
* :rtype: bool
*/
bool bool
pkgconf_queue_validate(pkgconf_client_t *client, pkgconf_list_t *list, int maxdepth, unsigned int flags) pkgconf_queue_validate(pkgconf_client_t *client, pkgconf_list_t *list, int maxdepth, unsigned int flags)
{ {