add a section about pointer validity

diff --git a/doc/libsolv.3 b/doc/libsolv.3
index 2cdf312..5d7e2c6 100644 (file)
--- a/doc/libsolv.3
+++ b/doc/libsolv.3
@@ -2,12 +2,12 @@
 .\"     Title: Libsolv
 .\"    Author: [see the "Author" section]
 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
-.\"      Date: 06/11/2013
+.\"      Date: 06/12/2013
 .\"    Manual: LIBSOLV
 .\"    Source: libsolv
 .\"  Language: English
 .\"
-.TH "LIBSOLV" "3" "06/11/2013" "libsolv" "LIBSOLV"
+.TH "LIBSOLV" "3" "06/12/2013" "libsolv" "LIBSOLV"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -47,6 +47,13 @@ fixed Ids for often used strings
 .RS 4
 access libsolv from perl/python/ruby
 .RE
+.SH "POINTER VALIDITY"
+.sp
+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\(cqs 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\&.
+.sp
+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\&.)
+.sp
+The language bindings already deal with pointer validity, so you do not have to worry about this issue when using the bindings\&.
 .SH "AUTHOR"
 .sp
 Michael Schroeder <mls@suse\&.de>

diff --git a/doc/libsolv.txt b/doc/libsolv.txt
index 7080d06..7908ca5 100644 (file)
--- 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>