add a section about pointer validity

1 files changed, 30 insertions, 0 deletions

diff --git a/doc/libsolv.txt b/doc/libsolv.txt
index 7080d06..7908ca5 100644
--- a/doc/libsolv.txt
+++ b/doc/libsolv.txt
@@ -3,10 +3,12 @@ Libsolv(3)
 :man manual: LIBSOLV
 :man source: libsolv
 
+
 Name
 ----
 libsolv - package dependency solver library using a satisfiability algorithm
 
+
 Documentation
 -------------
 The libsolv documentation is split into multiple parts:
@@ -20,6 +22,34 @@ The libsolv documentation is split into multiple parts:
 *libsolv-bindings*::
   access libsolv from perl/python/ruby
 
+
+Pointer Validity
+----------------
+Note that all pointers to objects that have an Id have only a limited
+validity period, with the exception of Repo pointers. There are only
+guaranteed to be valid until a new object of that type is added or an
+object of that type is removed. Thus pointers to Solvable objects are only 
+valid until another solvable is created, because adding a Solvable may
+relocate the Pool's Solvable array. This is also true for Pool strings,
+you should use solv_strdup() to create a copy of the string if you
+want to use it at some later time. You should use the Ids in the code
+and not the pointers, except for short times where you know that the
+pointer is safe.
+
+Note also that the data lookup functions or the dataiterator also
+return values with limited lifetime, this is especially true for data
+stored in the paged data segment of solv files. This is normally
+data that consists of big strings like package descriptions or is not
+often needed like package checksums. Thus looking up a description of
+a solvable and then looking up the description of a different solvable
+or even the checksum of the same solvable may invalidate the first
+result. (The dataiterator supports a dataiterator_strdup() function
+to create a safe copy.)
+
+The language bindings already deal with pointer validity, so you do
+not have to worry about this issue when using the bindings.
+
+
 Author
 ------
 Michael Schroeder <mls@suse.de>