doc/storage.md

   1 Storage library {#storage}
   2 ===============
   3
   4 This library provides a medium-level interface for accessing and
   5 manipulating file contents in memory.  Its purpose is to allow code
   6 parts developed independently from each other to use the same memory
   7 representation of objects while being able to rely on some invariants.
   8 In particular, it should be possible to access and manipulate objects
   9 without knowledge of the other modules' object system or metadata.
  10
  11 In practice, this means:
  12
  13 - An object is represented by exactly the information which is
  14   required to describe it.  Information which is only meaningful to
  15   some code parts is not managed by the library, such as pointers to
  16   shared data or weak references.  For example, the data structure
  17   representing a schematic net is:
  18 \code{.c}
  19     struct xornsch_net {
  20         struct xorn_double2d pos;
  21         struct xorn_double2d size;
  22         int color;
  23         bool is_bus;
  24         bool is_pin;
  25         bool is_inverted;
  26     };
  27 \endcode
  28
  29 - File contents are referred to by \ref xorn_revision_t "revisions"
  30   which are basically copy-on-write smart pointers.  Once a revision
  31   is marked as “final”, it is not possible make further changes to it
  32   by means of the library's functions.  (But it is of course possible
  33   to create a copy of the revision and modify that.)  This allows to
  34   keep tabs on a certain state of a file, making it easy to implement
  35   an undo/redo functionality.
  36
  37 - The actual data an object has in a revision is looked up and changed
  38   using a \ref xorn_object_t or \ref xorn_selection_t key which
  39   describes the “identity” of one or multiple objects, respectively.
  40
  41 The library's interface is designed to anticipate the operations which
  42 an application will typically perform on the file's contents and
  43 provide abstract functions which express these intentions to allow the
  44 library to do some optimization.  For example, to delete all circles
  45 and arcs with radius zero, instead of
  46
  47 \snippet motivation.c discrete
  48
  49 you would write:
  50
  51 \snippet motivation.c integrated
  52
  53 The implementation could now, for example, choose to express the
  54 selection as a filter which can be applied to individual objects
  55 rather than as a list of object pointers, if this should prove more
  56 efficient.  This way, the application doesn't have to know about but
  57 can still benefit from optimizations to the potentially messy detail
  58 of how the data is internally stored and accessed.
  59
  60 \sa xornstorage.h
  61 \sa \ref using-storage
  62
  63
  64 --------------------------------------------------------------------------------
  65
  66 Copyright (C) 2013-2020 Roland Lutz
  67
  68 Permission is granted to copy, distribute and/or modify this document
  69 under the terms of the [GNU Free Documentation License, Version 1.2]
  70 (http://www.gnu.org/licenses/old-licenses/fdl-1.2.html) or any later
  71 version published by the Free Software Foundation; with no Invariant
  72 Sections, with no Front-Cover Texts, and with no Back-Cover Texts.