diff options
Diffstat (limited to 'doc/c/world.rst')
-rw-r--r-- | doc/c/world.rst | 48 |
1 files changed, 48 insertions, 0 deletions
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. |