Skip to content

GitLab

Commit da3d8e50 authored by Marek Vavruša's avatar Marek Vavruša
Browse files
Options

doc: updated library doc

parent c9476458
Hide whitespace changes
Inline Side-by-side
Showing with 118 additions and 72 deletions
doc/index.rst
View file @ da3d8e50
......@@ -7,7 +7,7 @@ The project provides both a resolver library and a small daemon.
Modular architecture of the library keeps the core tiny and efficient, and provides a state-machine like API for extensions.
.. toctree::
:maxdepth: 4
:maxdepth: 2
build
lib
......
doc/lib.rst
View file @ da3d8e50
......@@ -5,25 +5,48 @@
API reference
=============
.. doxygengroup:: resolution
:project: libkresolve
.. contents::
:depth: 1
:local:
.. _lib_api_rplan:
Name resolution
---------------
.. doxygengroup:: resolution
:project: libkresolve
.. doxygengroup:: rplan
:project: libkresolve
.. _lib_api_cache:
Cache
-----
.. doxygengroup:: cache
:project: libkresolve
.. _lib_api_nameservers:
Nameservers
-----------
.. doxygengroup:: nameservers
:project: libkresolve
.. _lib_api_modules:
Modules
-------
.. doxygengroup:: modules
:project: libkresolve
Utilities
---------
.. doxygengroup:: utils
:project: libkresolve
......
lib/README.rst
View file @ da3d8e50
......@@ -15,31 +15,6 @@ Library layout
:local:
The library as described provides basic services for name resolution, which should cover the usage.
The following part is for those who are planning to hack on the library or develop modules, to give
you an idea about the API and the library layout.
Name resolution
---------------
.. _lib_rplan:
Resolution plan
---------------
.. _lib_cache:
Cache
-----
.. _lib_nameservers:
Nameservers
-----------
Utilities
~~~~~~~~~
.. warning:: Work in progress.
Resolving a name
----------------
......@@ -64,9 +39,9 @@ the :c:func:`iterate_layer`, and the :c:func:`itercache_layer`.
The library offers following services:
- :ref:`Cache <lib_cache>` - MVCC cache interface for retrieving/storing resource records.
- :ref:`Resolution plan <lib_rplan>` - Query resolution plan, a list of partial queries (with hierarchy) sent in order to satisfy original query. This contains information about the queries, nameserver choice, timing information, answer and its class.
- :ref:`Nameservers <lib_nameservers>` - Reputation database of nameservers, this serves as an aid for nameserver choice.
- :ref:`Cache <lib_api_cache>` - MVCC cache interface for retrieving/storing resource records.
- :ref:`Resolution plan <lib_api_rplan>` - Query resolution plan, a list of partial queries (with hierarchy) sent in order to satisfy original query. This contains information about the queries, nameserver choice, timing information, answer and its class.
- :ref:`Nameservers <lib_api_nameservers>` - Reputation database of nameservers, this serves as an aid for nameserver choice.
A processing layer is going to be called by the query resolution driver for each query,
so you're going to work with :ref:`struct kr_layer_param <lib_api_rplan>` as your per-query context. This structure contains pointers to
......
lib/generic/README.rst
View file @ da3d8e50
......@@ -6,18 +6,33 @@ such thing for C. It's either bloated, has poor interface, null-checking is abse
doesn't allow custom allocation scheme. BSD-licensed (or compatible) code is allowed here,
as long as it comes with a test case in `tests/test_generics.c`.
Data structures
~~~~~~~~~~~~~~~
* array_ - a set of simple macros to make working with dynamic arrays easier.
* map_ - a `Crit-bit tree`_ key-value map implementation (public domain) that comes with tests.
* set_ - set abstraction implemented on top of ``map``.
* pack_ - length-prefixed list of objects (i.e. array-list).
* ``array`` - a set of simple macros to make working with dynamic arrays easier.
* ``set`` - a `Crit-bit tree`_ simple implementation (public domain) that comes with tests.
* ``map`` - key-value map implemented on top of ``set``.
* ``pack`` - length-prefixed list of objects (i.e. array-list).
array
~~~~~
API reference and examples
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. doxygenfile:: array.h
:project: libkresolve
map
~~~
.. doxygenfile:: map.h
:project: libkresolve
set
~~~
.. doxygenfile:: set.h
:project: libkresolve
pack
~~~~
.. doxygengroup:: generics
.. doxygenfile:: pack.h
:project: libkresolve
.. _`Crit-bit tree`: http://cr.yp.to/critbit.html
lib/generic/array.h
View file @ da3d8e50
......@@ -15,18 +15,21 @@
*/
/**
* Generics - simple dynamic array.
*
* \note The C has no generics, so it is implemented mostly using macros.
* @file array.h
* @brief A set of simple macros to make working with dynamic arrays easier.
*
* @note The C has no generics, so it is implemented mostly using macros.
* Be aware of that, as direct usage of the macros in the evaluating macros
* may lead to different expectations, i.e.
* may lead to different expectations:
*
* # Undefined behaviour
* MIN(array_push(arr, val), other)
*
* May evaluate the code twice, leading to unexpected behaviour.
* This is a price to pay for absence of proper generics.
* May evaluate the code twice, leading to unexpected behaviour.
* This is a price to pay for the absence of proper generics.
*
* Example usage:
* Example usage:
*
* array_t(const char*) arr;
* array_init(arr);
......
lib/generic/map.h
View file @ da3d8e50
......@@ -4,11 +4,13 @@
*/
/**
* Generics - A Crit-bit tree 'map' implementation.
*
* @warning If the user provides a custom allocator, it must return addresses aligned to 2B boundary.
* @file map.h
* @brief A Crit-bit tree key-value map implementation.
*
* Example usage:
* @warning If the user provides a custom allocator, it must return addresses aligned to 2B boundary.
*
* Example usage:
*
* map_t map = map_make();
*
......
lib/generic/pack.h
View file @ da3d8e50
......@@ -15,34 +15,35 @@
*/
/**
* Generics - array of lenght-prefixed packed objects
* @file pack.h
* @brief A length-prefixed list of objects, also an array list.
*
* Each object is prefixed by item length, unlike array this structure
* permits variable-length data. It is also equivallent to forward-only list
* backed by an array.
*
* @note Maximum object size is 2^16 bytes, @see pack_objlen_t
* @note Maximum object size is 2^16 bytes, see ::pack_objlen_t
*
* Example usage:
*
* pack_t pack;
* pack_init(pack);
* pack_t pack;
* pack_init(pack);
*
* // Reserve 2 objects, 6 bytes total
* pack_reserve(pack, 2, 4 + 2);
*
* // Push 2 objects
* pack_obj_push(pack, U8("jedi"), 4)
* pack_obj_push(pack, U8("\xbe\xef"), 2);
* // Reserve 2 objects, 6 bytes total
* pack_reserve(pack, 2, 4 + 2);
*
* // Push 2 objects
* pack_obj_push(pack, U8("jedi"), 4)
* pack_obj_push(pack, U8("\xbe\xef"), 2);
*
* // Iterate length-value pairs
* uint8_t *it = pack_head(pack);
* while (it != pack_tail(pack)) {
* uint8_t *val = pack_obj_val(it);
* it = pack_obj_next(it);
* }
* // Iterate length-value pairs
* uint8_t *it = pack_head(pack);
* while (it != pack_tail(pack)) {
* uint8_t *val = pack_obj_val(it);
* it = pack_obj_next(it);
* }
*
* pack_clear(pack);
* pack_clear(pack);
*
* \addtogroup generics
* @{
......@@ -52,6 +53,10 @@
#include <string.h>
#include "array.h"
#ifdef __cplusplus
extern "C" {
#endif
/** Packed object length type. */
typedef uint16_t pack_objlen_t;
......@@ -115,4 +120,10 @@ static inline int pack_obj_push(pack_t *pack, const uint8_t *obj, pack_objlen_t
memcpy(endp + sizeof(len), obj, len);
pack->len += packed_len;
return 0;
}
\ No newline at end of file
}
#ifdef __cplusplus
}
#endif
/** @} */
lib/generic/set.h
View file @ da3d8e50
/* Copyright (C) 2015 CZ.NIC, z.s.p.o. <knot-dns@labs.nic.cz>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/**
* Generics - A Crit-bit set implementation.
* @file set.h
* @brief A set abstraction implemented on top of map.
*
* @note The API is based on @fn map.h, see it for more examples.
* @note The API is based on map.h, see it for more examples.
*
* Example usage:
* Example usage:
*
* set_t set = set_make();
*
......@@ -83,4 +100,4 @@ typedef int (set_walk_cb)(const char *, void *);
}
#endif
/** @} */
\ No newline at end of file
/** @} */
lib/rplan.h
View file @ da3d8e50
......@@ -30,7 +30,7 @@
#include "lib/cache.h"
#include "lib/zonecut.h"
/* Query flags */
/** Query flags */
enum kr_query_flag {
QUERY_NO_MINIMIZE = 1 << 0, /**< Don't minimize QNAME. */
QUERY_TCP = 1 << 1 /**< Use TCP for this query. */
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment