Changes between Version 1 and Version 2 of PythonGotchas

Timestamp:

Sep 20, 2010, 9:04:28 AM (14 years ago)

Author:

jjr8

Comment:

--

PythonGotchas

@@ -41 +41 @@
 
 The GDAL team acknowledges that Python programmers expect exceptions to be enabled by default, but says that exceptions are disabled by default to [http://lists.osgeo.org/pipermail/gdal-dev/2010-September/026031.html preserve backward compatibility].
+
+=== Python crashes if you use an object after deleting an object it was related to ===
+
+Consider this example:
+
+{{{
+#!python
+>>> from osgeo import gdal
+>>> dataset = gdal.Open('C:\\RandomData.img')
+>>> band = dataset.GetRasterBand(1)
+>>> print band.Checksum()
+31212
+}}}
+
+In this example, {{{band}}} has a relationship with {{{dataset}}} that requires {{{dataset}}} to remain allocated in order for {{{band}}} to work. If we delete {{{dataset}}} and then try to use {{{band}}}, Python will crash:
+
+{{{
+#!python
+>>> from osgeo import gdal
+>>> dataset = gdal.Open('C:\\RandomData.img')
+>>> band = dataset.GetRasterBand(1)
+>>> del dataset           # This will cause the Python garbage collector to deallocate dataset
+>>> band.GetChecksum()    # This will now crash Python because the band's dataset is gone
+< Python crashes >
+}}}
+
+This problem can manifest itself in subtle ways. For example, can occur if you try to instantiate a temporary dataset instance within a single line of code:
+
+{{{
+#!python
+>>> from osgeo import gdal
+>>> print gdal.Open('C:\\RandomData.img').GetRasterBand(1).Checksum()
+< Python crashes >
+}}}
+
+In this example, the dataset instance was no longer needed after the call to {{{GetRasterBand()}}} so Python deallocated it ''before'' calling {{{Checksum()}}}.
+
+This problem occurs because the GDAL and OGR objects are implemented in C++ and the relationships between them are maintained in C++ using pointers. When you delete the dataset instance in Python it causes the C++ object behind it to be deallocated. But the C++ object behind the band instance does not know that this happened, so it contains a pointer to the C++ dataset object that no longer exists. When the band tries to access the non-existing object, the process crashes.
+
+The GDAL team knows that this design is not what Python programmers expect. Unfortunately the design is difficult to correct so it is likely to remain for some time. Please consult the GDAL team for more information.
+
+The problem is not restricted to the GDAL band and dataset objects. It happens in other areas where objects have relationships with each other. Unfortunately there is no complete list, so you have to watch for it yourself. One other known place involves the OGR {{{GetGeometryRef()}}} function:
+
+{{{
+#!python
+>>> feat = lyr.GetNextFeature()
+>>> geom = feat.GetGeometryRef()     # geom contains a reference into the C++ geometry object maintained by the C++ feature object
+>>> del feat                         # This deallocates the C++ feature object, and its C++ geometry
+>>> print(geom.ExportToWkt())        # Crash here. The C++ geometry no longer exists
+< Python crashes >
+}}}
+
+If you read the GDAL and OGR API documentation carefully, you will see that the functions that end in "Ref" mention that they transfer ownership of objects. This is a clue that the problem could occur. Be careful when using the "Ref" functions. Also watch out for functions that end in "Directly", such as {{{SetGeometryDirectly()}}}. 
+
+{{{
+#!python
+>>> point = ogr.Geometry(ogr.wkbPoint)
+>>> feature = ogr.Feature(layer_defn)
+>>> feature.SetGeometryDirectly(point)    # Transfers ownership of the C++ geometry from point to feature
+>>> del feature                           # point becomes implicitly invalid, because feature owns the C++ geometry
+>>> print point.ExportToWkt()             # Crash here
+< Python crashes >
+}}}
+
+The advantage of the "Ref" and "Directly" functions is they provide faster performance because a duplicate object does not need to be created. The disadvantage is that you have to watch out for this problem.
+
+The examples here are based on [http://lists.osgeo.org/pipermail/gdal-dev/2010-September/026027.html email from Even Rouault].
+
+=== Certain objects contain a {{{Destroy()}}} method, but you should never use it ===
+
+
 
 = Gotchas fixed in GDAL 1.8.0 =