MS RFC 24: Mapscript memory management¶

Date: 2006/12/3
Author: Umberto Nicoletti
Contact: umberto.nicoletti@gmail.com
Last Edited: 2006/12/31
Status: Proposed
Version: MapServer 5.0

0. Warning!¶

IMPORTANT: this is the first and obsolete version fo the rfc, which is kept here only for reference purposes and for a limited time.

1. Overview¶

Memory management in SWIG wrappers has a tradition of being difficult and error prone. The programmer of the wrapper has to deal with memory that can be allocated and then freed in two separate environments: the hosting language such as Java, C# or Perl and the wrapped native code.

Most modern languages implement garbage collection, so that the developer does not have to care about memory management. The programming language tracks memory (or objects, really) allocations and when an object goes out of scope (it is no more reachable from the running program) it marks it as eligible for garbage collection. A background process once in a while wakes up and frees the memory associated with marked objects. For the details on GC see this wikipedia entry: http://en.wikipedia.org/wiki/Garbage_collection_(computer_science)

What happens in most cases is that some memory is allocated in, say, Java, then another pointer is pointed to it by invoking some wrapped method. Eventually the GC runs and frees the memory. As soon as the other pointers are dereferenced the hosting language will crash because of a segmentation fault error (in Unix terms).

MapServer SWIG wrappers suffer from issues with garbage collections for example in dinamically adding layers to a map.

The purpose of this RFC is to address these issues and provide a solution that can be implemented in time for the release of MapServer 5.0.

This RFC does not address thread safety.

2. Problem description¶

This section gives an overview (along with examples) of errors in mapscript memory management. Most of the examples will be in Java, but they apply to all other mapscripts too. They can be reproduced against the latest CVS code of mapserver-HEAD as of 31st December 2006.

2.1 Object equality/identity¶

Consider the following Java mapscript code:

mapObj map=new mapObj("my.map");
layerObj layer=new layerObj(null);
// add layer to the map
int index=map.insertLayer(layer, -1);
// set its name
layer.setName("Change me");

// fetch from map
layerObj newLayer=map.getLayer(index);
// they should be the same...
System.out.println(newLayer.getName()+"=="+layer.getName());
// and this should print true (it is a reference comparison)
System.out.println(newLayer==layer);

when executed will produce the following output:

null==Change me
false

This happens because the current implementation strategy copies the layer when it is inserted into the map. The Java reference is not re-pointed to the new copy and is therefore ‘disconnected’ from the actual memory area. This currently happens for the most used insert methods (i.e. insertClass).

2.2 Early garbage collection¶

Objects created through mapscript can be garbage-collected “early”, when there are live objects still referencing them. See this example in Java:

mapObj map=new mapObj("data/emptymap.map");

layerObj layer=new layerObj(map);
layer.setName("Layer 0");
classObj clazz=new classObj(null);
clazz.setName("Clazz 0 NULL");
int pos=layer.insertClass(clazz, -1);

map=null;
layer=null;

// force garbage collection
for(int i=0;i<100;i++)
        System.gc();

clazz.getLayer().getMap().draw();
// Java crashes because memory has been freed!

and its perl equivalent:

use mapscript;

$map = new mapscript::mapObj("../../tests/test.map");
$layer = new mapscript::layerObj($map);

print "Before first draw for $layer->{map}\n";
$layer->{map}->draw();
print "Map drawn, now undef map\n";
$map = undef;
$map1=$layer->{map}->draw();
// perl interpreter segfault

2.3 Dynamically populated layers, classes, etc¶

See the following bug reports:

http://mapserver.gis.umn.edu/bugs/show_bug.cgi?id=1400

http://mapserver.gis.umn.edu/bugs/show_bug.cgi?id=1743

http://mapserver.gis.umn.edu/bugs/show_bug.cgi?id=1841

Please note that this issue can be difficult to reproduce, credits go to Tamas for pointing it out.

3. Proposed implementation¶

To solve the problems shown at items 2.1, 2.2 and 2.3 this RCF proposes that:

each mapscript wrapper objects acting as a container or as content will have its mapscript language class augmented to maintain references to the contained objects and, when it is available, to the container object. These references allow the GC to make better informed decisions on which objects can be freed. From now on, and only for the purpose of this RFC, we will call cache these references.
getters must be wrapped so that they look up references in the cache first and setters/mutators must be wrapped so that they keep the references in the cache up to date when they are changed
when an object has a non-null parent its memory must be disowned (in SWIG terms) and owned when it is removed from the parent

This RFC should be applicable (with the necessary modifications) to all mapscript languages. Examples will be given for Perl or Java because of the author familiarity with these languages.

The three items above are described in more detail in the following subsections. Subsections 3.4 and 3.5 offer an implementation example for the layerObj class. Please note that in the following we limit the scope of our analysis to the classes/layer relationship.

3.1 Add references to the mapscript wrapper object¶

The mapscript objects will be modified so that they keep a reference to the other mapscript objects added to them or they are added to, exactly like the C struct does.

In example, in the case of the layerObj the layerObj class will be extended to contain

a reference to the mapObj that contains the layer
an array of classObjs

The purpose of these changes is that whenever a class is added to the layer the corresponding object is also added to the class array (the cache). The same when a classObj is returned as a result to getClass. By doing so the hosting language knows of the web of relations between these objects and we solve the early garbage collection problem.

The problem of object equality/identity is also resolved if we modify the getClass method to look first in the class array (the cache) and only after in the C data structures, as shown above.

3.2 Keep cache and C internal structure in sync¶

For the mechanism described at the previous item to work some functions in the mapscript objects and in the native code must be modified so that the mapscript objects and the C data structures stay in sync.

Returning to the example of the layerObj the insertClass, getClass and removeClass methods will have to be modified to keep the cache in sync with the C data structures. The current methods will be modified by using specific typemaps. The constructor will also need to be modified to store the reference to the mapObj. Eventually also the native code actually performing the copy-and-insert operation must be modified to only perform the insert operation (layerobject.c, line 52, function msInsertClass).

The API will be kept backward compatible whenever possible.

3.3 Disown memory allocated by swig for objects with non-null parents¶

The patch suggested by Tamas (bug 1743) must be extended so that memory is disowned also when a layer is inserted into a map and ported to all mapscript languages.

3.4 JAVA: mapscript code example for layerObj¶

Code example for layerObj (javamodule.i):

/*
   Modified constructor according to:
   - bug#1743, item 3.3
   - cache population and sync, item 3.2
*/
%typemap(javaconstruct) layerObj(mapObj map) %{ {
        this($imcall, true);
        if (map != null) {
                this.swigCMemOwn = false;
                /* Store reference in field member*/
                this.map=map;
                /* Add myself to the layers array of the map */
                map.layers[this.getIndex()];
        }
}
%}

%typemap(javaout) int insertClass {
        // call the C API, which needs to be modified
        // so that the classObj is not copied anymore
        int actualIndex=$jnicall;
        classes[actualIndex]=classobj;
        // disown the classObj just inserted, item 3.3
        classobj.swigCMemOwn=false;
        return actualIndex;
}

%typemap(javaout) classObj *getClass {
                if (classes[i]!=null)
                        return classes[i];

                long cPtr = $jnicall;
                classObj result = (cPtr == 0) ? null : new classObj(cPtr, false);

                if (result!=null)
                        classes[i]=result;
                return result;
}

%typemap(javacode) layerObj %{
        /* an array of classes to keep referenced objects alive and prevent
           their garbage collection, item 3.1
        */
        classObj[] classes=new classObj[mapscriptConstants.MS_MAXCLASSES];
        /* same for the map, item 3.1
        */
        mapObj map=null;
%}

3.5 PERL: mapscript code example for layerObj¶

Code example for layerObj (plmodule.i):

%feature("shadow") ~mapObj() %{
sub DESTROY {
        return unless $_[0]->isa('HASH');
        my $self = tied(%{$_[0]});
        return unless defined $self;
        delete $ITERATORS{$self};
        if (exists $OWNER{$self}) {
                mapscriptc::delete_mapObj($self);
                delete $OWNER{$self};
        }
        delete $mapscript::MAPLAYERS{$self};
}
%}

%feature("shadow") layerObj(mapObj *map)
%{
sub new {
        my $pkg = shift;
        my $self = mapscriptc::new_layerObj(@_);
        bless $self, $pkg if defined($self);
        if (defined($_[0])) {
                $self->DISOWN();
                mapscript::LAYER_ADD_MAP_REF($self, $_[0]);
                mapscript::MAP_ADD_LAYER_REF($_[0], $self);
        }
        return $self;
}
%}

%feature("shadow") ~layerObj()
%{
sub DESTROY {
        return unless $_[0]->isa('HASH');
        my $self = tied(%{$_[0]});
        return unless defined $self;
        delete $ITERATORS{$self};
        if (exists $OWNER{$self}) {
                mapscriptc::delete_layerObj($self);
                delete $OWNER{$self};
        }
        delete $mapscript::LAYERMAP{$self};
}
%}

%perlcode %{
        %LAYERMAP={};
        sub LAYER_ADD_MAP_REF {
                my ($layer, $map)=@_;
                #print "MAP key=" . tied(%$layer) . "\n";
                $LAYERMAP{ tied(%$layer) }=$map;
        }

        %MAPLAYERS={};
        sub MAP_ADD_LAYER_REF {
                my ($map, $layer)=@_;
                my $layers=$MAPLAYERS{ tied(%$map) };
                if (defined($layers)) {
                        $layers->{$layer->{index}}=$layer;
                } else {
                        $layers={};
                        $layers->{$layer->{index}}=$layer;
                }
                $MAPLAYERS{tied(%$map)}= $layers;
        }

        sub map_get {
                my $layer=@_[0];
                #print "GET MAP key" . $layer . "\n";
                if ( $LAYERMAP{ $layer } ) {
                        return \%{$LAYERMAP{$layer}};
                }
                return mapscriptc::layerObj_map_get(@_);
        }

        ##################
        # DEBUGGING ONLY #
        ##################
        sub getLayerFrom {
                my ($map, $idx)=@_;
                return $MAPLAYERS{tied(%$map)}->{$idx};
        }

        sub getMAPLAYERS {
                return \%MAPLAYERS;
        }
%}

Note: this example implements a bidirectional cache (map->layers and layer->map), but this does not play well with Perl reference-count based GC and will cause memory leaks. To address this limitation Perl mapscript will only implement the layer->map or child->parent side of the cache as described in 4.3.

4. Implementation plan¶

It seems that for most mapscripts (java, csharp, perl and python) there is enough functionality in SWIG to implement the features described in this RFC. For ruby we’ll probably have to go a different route and implement the %trackobjects feature. As of Tcl I currently don’t know if it’s possible.

The two following section describe in detail the required SWIG-mapscript features (injection of code and constructor customization). Each language gets then a specific section to deal with its own characteristics

4.1 Checking SWIG-Mapscript capabilities: %javacode¶

Swig provides the equivalent of %javacode for the following languages:

perl through %perlcode
python through %pythoncode
csharp through %cscode
ruby does not have any ruby code at all in its wrapper objects
swig-Tcl doesn’t support a %tclcode construct

This swig construct will be used to inject in the wrapper the definition for the references described in 3.1 and the wrapper methods.

4.1 Checking SWIG-Mapscript capabilities: constructor customization¶

The %csconstruct used to wrap and customize the costructor of mapscript objects (item 3.3) is only available in csharp and java. It should be possible to simulate its behaviour with %pythonprepend or %pythonprepend in python and with %perlcode or %feature(“shadow”) in perl.

This swig construct will be used to disown memory allocated by SWIG when the object has a reference to a valid parent (bug 1743).

4.2 Java and C-Sharp¶

SWIG-Java and SWIG-CSharp share a common ground and are therefore very similar. The names of SWIG-Java constructs can be roughly translated into their C-Sharp equivalents by changing the java prefix into cs (i.e. javacode in cscode, javaconstruct in csconstruct and javaout in csout).

The implementation should follow exactly this RCF.

4.3 Perl¶

As in the example above most of the perl customization can be done with the use of the shadow construct.

The implementation will differ from the RFC in the following manners:

1) the Perl wrapper will maintain references only in one direction (layer -> map, or generally contained -> container) and not both because of the implementation of the Perl GC (http://www.perl.com/doc/manual/html/pod/perlobj.html). If we had circular references this island of objects would normally never be garbage collected.

2) to wrap the layerObj->{map} invocation we must edit the mapscript.pm file manually. To overcome this limitation and automate find/replace we will use perl pies in the Makefile like the following two:

perl -pi -e "s/\*swig_map_get = \*mapscriptc::layerObj_map_get/\*swig_map_get = \*mapscript::map_get/" mapscript.pm
perl -pi -e "s/\*getMap = \*mapscriptc::layerObj_getMap/\*swig_map_get = \*mapscript::map_get/" mapscript.pm

4.4 Python¶

Python enjoys first-grade support in SWIG so the RFC should be implemented exactly as described. Differently from Perl Python’s GC can find and free cycles of objects (http://arctrix.com/nas/python/gc/).

4.5 Ruby¶

Needs investigation, probably we’ll have to use rb_gc_* functions to mark objects and prevent their garbage collection or use %trackobjects. Ruby will not implement this RFC.

4.6 Tcl¶

Needs investigation and a Tcl expert. At the time of this writing Tcl will probably not implement this RFC.

5.1 Implementation checklist¶

The following table will be used to track the implementation status of this RFC. There is a table for each mapscript object and when a language has implemented this RFC for a given object the maintainer will populate the relative cell with one of the following marks:

> if cache and wrappers have been implemented in the parent->child direction
< if cache and wrappers have been implemented in the child->parent direction
<> if cache and wrappers have been implemented in both directions
a plus sign (+) if object has been disowned
a minus sign (-) if object has been owned

5.2 mapObj¶

Method	java	C#	perl	python	tcl	ruby
getSymbolset
getFontset
getLabelcache
getExtent
setSaved_extent
getSaved_extent
getImagecolor
getOutputformat
getReference
getScalebar
getLegend
getQuerymap
getWeb
getConfigoptions
insertLayer
removeLayer
getLayer
getLayerByName
prepareImage
setOutputFormat
draw
drawQuery
drawLegend
drawScalebar
drawReferenceMap
getLabel
nextLabel
getOutputFormatByName
appendOutputFormat
removeOutputFormat

5.3 layerObj¶

Method	java	C#	perl	python	tcl	ruby
layerObj (constructor)
getMap
getOffsite
getMetadata
cloneLayer
insertClass
removeClass
nextShape
getFeature
getShape
getResult
getClass
getResults
addFeature
getExtent

5.4 classObj¶

Method	java	C#	perl	python	tcl	ruby
classObj (constructor)
getLabel
getMetadata
getLayer
clone
createLegendIcon
drawLegendIcon
getStyle
insertStyle
removeStyle

5.5 webObj¶

Method	java	C#	perl	python	tcl	ruby
webObj (constructor)
getMap
getExtent
setExtent
getMetadata

5.5 styleObj¶

For styleObjs it is enough to disown them when they are fetched from the container object. It is not necessary to add the reference pointing back to the container object.

Method	java	C#	perl	python	tcl	ruby
styleObj (constructor)
setColor
getColor
getBackgroundcolor
setBackgroundcolor
getOutlinecolor
setOutlinecolor
getMincolor
setMincolor
getMaxcolor
setMaxcolor
clone

5.6 labelObj¶

For labelObjs it is enough to disown them when they are fetched from the container object. It is not necessary to add the reference pointing back to the container object.

Method	java	C#	perl	python	tcl	ruby
labelObj (constructor)
getColor
setColor
setOutlinecolor
getOutlinecolor
setShadowcolor
getShadowcolor
getBackgroundcolor
setBackgroundcolor
setBackgroundshadowcolor
getBackgroundshadowcolor

5.7 hashTableObj¶

For hashTableObjs it is enough to disown them when they are fetched from the container object (i.e. a layerObj). It is not necessary to add the reference pointing back to the container object.

Method	java	C#	perl	python	tcl	ruby
hashTableObj (constructor)

5.8 colorObj¶

For colorObjs it is enough to disown them when they are fetched from the container object. It is not necessary to add the reference pointing back to the container object.

Method	java	C#	perl	python	tcl	ruby
colorObj (constructor)

5.9 imageObj¶

For imageObjs it is enough to own them when they are fetched from the container object. It is not necessary to add the reference pointing back to the container object.

Method	java	C#	perl	python	tcl	ruby
imageObj (constructor)

5.10 shapeObj¶

For shapeObjs it is enough to set ownership properly when they are fetched from or added to the container object. It is not necessary to add the reference pointing back to the container object.

Method	java	C#	perl	python	tcl	ruby
shapeObj (constructor)
getLine
getBounds
get
add
clone
copy
buffer
convexHull
boundary
getCentroid
Union
intersection
difference
symDifference

5.11 lineObj¶

For lineObjs it is enough to set ownership properly when they are fetched from or added to the container object. It is not necessary to add the reference pointing back to the container object.

Method	java	C#	perl	python	tcl	ruby
lineObj (constructor)
getPoint
get
add
set

5.12 pointObj¶

For pointObjs it is enough to set ownership properly when they are fetched from or added to the container object. It is not necessary to add the reference pointing back to the container object.

Method	java	C#	perl	python	tcl	ruby
pointObj (constructors)
toShape

5.13 symbolsetObj¶

For symbolsetObjs it is not necessary to add the reference pointing back to the map.

Method	java	C#	perl	python	tcl	ruby
symbolsetObj (constructor)
setSymbol(symbolObj value)
getSymbol
getSymbol(int i)
getSymbolByName
index
appendSymbol
removeSymbol

5.14 symbolObj¶

For symbolObjs it is enough to set ownership properly when they are fetched from or added to the container object. It is not necessary to add the reference pointing back to the container object.

Method	java	C#	perl	python	tcl	ruby
symbolObj (constructor)
setPoints
getPoints
getImage
setImage

6. Open issues¶

Fetching an object from a map and then adding it to another map is likely to cause a segfault. The solution would be to remove it from the first map and then add it the second or implement a check before updating the reference to its parent and bail out (throw and exception).

7. Status¶

RFC opened for comments on Jan, the 10th 2007 with a post on mapserver-dev. RFC undergoing revision after discussion on mapserver-dev.

	Home \| Products \| Issue Tracker \| Service Providers \| FAQ \| Twitter \| Download \|

DOCS PREVIEW