From f8a59da9c492b7df38f53ba96505313e931d76cc Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sun, 28 Mar 2021 13:42:35 -0400 Subject: Add high-level documentation --- doc/c/world.rst | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 doc/c/world.rst (limited to 'doc/c/world.rst') diff --git a/doc/c/world.rst b/doc/c/world.rst new file mode 100644 index 00000000..31cbe16b --- /dev/null +++ b/doc/c/world.rst @@ -0,0 +1,48 @@ +World +===== + +.. default-domain:: c +.. highlight:: c + +So far, we have only used nodes and statements, +which are simple independent objects. +Higher-level facilities in Serd require a :struct:`SerdWorld`, +which represents the global library state. + +A program typically uses just one world, +which can be constructed using :func:`serd_world_new`: + +.. literalinclude:: overview_code.c + :start-after: begin world-new + :end-before: end world-new + :dedent: 2 + +All "global" library state is handled explicitly via the world. +Serd does not contain any static mutable data, +allowing it to be used concurrently in several parts of a program, +for example in plugins. + +If multiple worlds *are* used in a single program, +they must never be mixed: +objects "inside" one world can not be used with objects inside another. + +Note that the world is not a database, +it only manages a small amount of library state for things like configuration and logging. + +Generating Blanks +----------------- + +Blank nodes, or simply "blanks", +are used for resources that do not have URIs. +Unlike URIs, they are not global identifiers, +and only have meaning within their local context (for example, a document). +The world provides a method for automatically generating unique blank identifiers: + +.. literalinclude:: overview_code.c + :start-after: begin get-blank + :end-before: end get-blank + :dedent: 2 + +Note that the returned pointer is to a node that will be updated on the next call to :func:`serd_world_get_blank`, +so it is usually best to copy the node, +like in the example above. -- cgit v1.2.1