diff --git a/doc/libpkgconf-queue.rst b/doc/libpkgconf-queue.rst new file mode 100644 index 0000000..e1af6a5 --- /dev/null +++ b/doc/libpkgconf-queue.rst @@ -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 diff --git a/doc/libpkgconf.rst b/doc/libpkgconf.rst index 5a8ee66..da31a05 100644 --- a/doc/libpkgconf.rst +++ b/doc/libpkgconf.rst @@ -10,3 +10,4 @@ libpkgconf - an API for managing `pkg-config` modules libpkgconf-client libpkgconf-dependency libpkgconf-path + libpkgconf-queue diff --git a/libpkgconf/queue.c b/libpkgconf/queue.c index c6bef99..595a004 100644 --- a/libpkgconf/queue.c +++ b/libpkgconf/queue.c @@ -15,11 +15,35 @@ #include +/* + * !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 { pkgconf_node_t iter; char *package; } 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 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); } +/* + * !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 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); } +/* + * !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 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); } +/* + * !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 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; } +/* + * !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 pkgconf_queue_validate(pkgconf_client_t *client, pkgconf_list_t *list, int maxdepth, unsigned int flags) {