[mapserver-commits] r8145 - trunk/docs/development/rfc
svn at osgeo.org
svn at osgeo.org
Sun Nov 30 15:52:18 EST 2008
Author: hobu
Date: 2008-11-30 15:52:18 -0500 (Sun, 30 Nov 2008)
New Revision: 8145
Modified:
trunk/docs/development/rfc/ms-rfc-24.txt
Log:
styling, break at 80, formatting
Modified: trunk/docs/development/rfc/ms-rfc-24.txt
===================================================================
--- trunk/docs/development/rfc/ms-rfc-24.txt 2008-11-30 20:20:45 UTC (rev 8144)
+++ trunk/docs/development/rfc/ms-rfc-24.txt 2008-11-30 20:52:18 UTC (rev 8145)
@@ -13,34 +13,55 @@
:Tracker: http://trac.osgeo.org/mapserver/ticket/2032
:Tracker 3.2: http://trac.osgeo.org/mapserver/ticket/2442
-1. Overview
+
+.. sectnum::
+
+.. contents:: Table of Contents
+ :depth: 2
+ :backlinks: top
+
+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.
+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:
+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).
+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.
+Mapserver SWIG wrappers suffer from issues with garbage collections for example
+in dynamically 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.
+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
+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
+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.
+
+Object equality/identity
++++++++++++++++++++++++++++
-Consider the following Java mapscript code:
+
+Consider the following Java MapScript code:
::
mapObj map=new mapObj("my.map");
@@ -59,6 +80,7 @@
when executed will produce the following output:
+
::
null==Change me
@@ -69,10 +91,13 @@
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
+Early garbage collection
++++++++++++++++++++++++++++
-Objects created through mapscript can be garbage-collected "early", when there are live objects still referencing them.
+
+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");
@@ -93,7 +118,8 @@
clazz.getLayer().getMap().draw();
// Java crashes because memory has been freed!
-and its perl equivalent:
+and its Perl equivalent:
+
::
use mapscript;
@@ -109,67 +135,83 @@
// perl interpreter segfault
-2.3 Dynamically populated layers, classes, etc
+Dynamically populated layers, classes, etc
++++++++++++++++++++++++++++++++++++++++++++++
+
See the following bug reports:
-http://mapserver.gis.umn.edu/bugs/show_bug.cgi?id=1400
+http://trac.osgeo.org/mapserver/ticket/1400
-http://mapserver.gis.umn.edu/bugs/show_bug.cgi?id=1743
+http://trac.osgeo.org/mapserver/ticket/1743
-http://mapserver.gis.umn.edu/bugs/show_bug.cgi?id=1841
+http://trac.osgeo.org/mapserver/ticket/1841
Please note that this issue can be difficult to reproduce, credits go to Tamas
for pointing it out.
-3. Proposed implementation
+Proposed implementation
--------------------------
-To solve the problems shown at items 2.1, 2.2 and 2.3 this RCF proposes that:
-1. a reference counter is added to each mapserver data structure that can be manipulated directly with mapscript AND inserted/added to another object (i.e. a layerObj)
+To solve the problems shown at items 2.1, 2.2 and 2.3 this RFC proposes that:
-2. setters, getters and insert methods increase the counter whenever a reference to a mapserver data structure is created by mapscript
+1. a reference counter is added to each MapServer data structure that can be
+ manipulated directly with MapScript AND inserted/added to another
+ object (i.e. a layerObj)
-3. all mapscript objects be always owned by SWIG or, more exactly, by the wrapper objects (*swigCMemOwn* is always true)
+2. setters, getters and insert methods increase the counter whenever a
+ reference to a MapServer data structure is created by MapScript
-4. the mapserver free* methods be modified so that the the underlying data structure is freed only when the counter is zero and decrease it otherwise
+3. all MapScript objects be always owned by SWIG or, more exactly, by the
+ wrapper objects (*swigCMemOwn* is always true)
-5. wrapper objects be augmented to mantain a reference to their parents only and prevent early garbage collection
+4. the MapServer free* methods be modified so that the the underlying data
+ structure is freed only when the counter is zero and decrease it otherwise
-6. all arrays of structures (map->layers and so on) be changed to arrays of pointers to eliminate the need for a copy operation on insert methods
+5. wrapper objects be augmented to maintain a reference to their parents
+ only and prevent early garbage collection
-By preliminary discussion it has been decided to drop the requirement to fully support object equality.
-As a result 2.1 will be implemented so that *only* the first comparison returns true.
+6. all arrays of structures (map->layers and so on) be changed to arrays of
+ pointers to eliminate the need for a copy operation on insert methods
-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.
+By preliminary discussion it has been decided to drop the requirement to
+fully support object equality. As a result 2.1 will be implemented so
+that *only* the first comparison returns true.
-The 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
+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 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 Implement a reference counter
+Implement a reference counter
+++++++++++++++++++++++++++++++++
-The mapscript objects implementing this rfc will get a new *int* member
+
+The MapScript objects implementing this rfc will get a new *int* member
called *refcount*.
Mapscript will keep read-only access to the reference counter which is useful
for debugging
-The reference counter increment and decrement will be implemented by the following
-macros:
+The reference counter increment and decrement will be implemented by the
+following macros:
+
::
#define MS_REF_INCR(obj) obj->refcount++
#define MS_REF_DECR(obj) (--(obj->refcount))
-An alternative could be to keep the reference counting in a global hashmap, keyed by memory address.
-This will eliminate the need for a change to *every* object but might present
-a greater impact on performance. In particular the hash function must be choosen carefully.
+An alternative could be to keep the reference counting in a global hashmap,
+keyed by memory address. This will eliminate the need for a change to *every*
+object but might present a greater impact on performance. In particular the
+hash function must be chosen carefully.
http://en.wikipedia.org/wiki/Hash_table
-The example implementation proposed at the tracker bug #2032 adopts the first strategy.
+The example implementation proposed at the tracker `bug #2032`_ adopts the
+first strategy.
3.1.1 RefCounting in the CGI
****************************
@@ -177,14 +219,14 @@
requirement is dropped on the following motivations:
a. with the advent of use_mapscript the compilation process will be
-different if the user needs to build mapscript rather than the cgi.
-While this should not be a big deal for individuals it might place
-some extra burden on those maintaining binary distros like ms4w or
-fwtools
+ different if the user needs to build MapScript rather than the cgi.
+ While this should not be a big deal for individuals it might place
+ some extra burden on those maintaining binary distros like ms4w or
+ fwtools
b. having refcounting enabled does not harm the cgi which should only
-experience a tini tiny (if any at all) performance drop because of the
-extra if and ++
+ experience a tini tiny (if any at all) performance drop because of the
+ extra if and ++
c. we can always opt to introduce USE_MAPSCRIPT later
@@ -200,9 +242,11 @@
2. a new *configure* option is added that is called *--enable-mapscript*
-3. starting from 5.0 on it will be required to specify *--enable-mapscript* to build any mapscript (with the exception of php, maybe)
+3. starting from 5.0 on it will be required to specify *--enable-mapscript*
+ to build any MapScript (with the exception of php, maybe)
Example:
+
::
/* CLASS OBJECT - basic symbolization and classification information */
@@ -224,38 +268,49 @@
+1: Umberto, Tamas and Daniel
-3.2 Add references to the mapscript wrapper object
+Add references to the MapScript wrapper object
++++++++++++++++++++++++++++++++++++++++++++++++++
-The mapscript objects will be modified so that they keep a reference to
-the other mapscript objects they are added to, like
-the C struct already does. This object can be hereafter referred to as the *parent object*.
-In example, in the case of the layerObj the layerObj class will be extended to contain
+The MapScript objects will be modified so that they keep a reference to the
+other MapScript objects they are added to, like the C struct already does.
+This object can be hereafter referred to as the *parent object*.
+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
-The purpose of these changes is that the hosting language knows of the relationships
-between these objects and we solve the early garbage collection problem. This is also important
-to avoid unexpected crashes in the hosting language when the layer dereferences its parent object
+The purpose of these changes is that the hosting language knows of the
+relationships between these objects and we solve the early garbage collection
+problem. This is also important to avoid unexpected crashes in the hosting
+language when the layer dereferences its parent object
(*grep 'layer->map' *.c* reports 105 usages).
-As stated earlier, it has been decided to drop the requirement to fully support object equality/identity.
+As stated earlier, it has been decided to drop the requirement to fully
+support object equality/identity.
-This item will be implemented in a second phase, after the basic refcounting is in place. Also the rfc proposes to implement a parent not-null check for the layer operations that use the parent map reference.
+This item will be implemented in a second phase, after the basic refcounting
+is in place. Also the rfc proposes to implement a parent not-null check for
+the layer operations that use the parent map reference.
-3.3 Change arrays of structures in arrays of pointers
+Change arrays of structures in arrays of pointers
+++++++++++++++++++++++++++++++++++++++++++++++++++++
-This change will occurr at the C-level and is quite an undertaking. Initially and for the purpose of
-this RFC the size of the arrays will still be fixed as it is now. The modification of the code
-will be made a way that future RFC addressing dynamically-sized arrays can build upon.
+This change will occurr at the C-level and is quite an undertaking. Initially
+and for the purpose of this RFC the size of the arrays will still be fixed as
+it is now. The modification of the code will be made a way that future RFC
+addressing dynamically-sized arrays can build upon.
+
The strategy is as follows:
-1. all accesses to array elements could be wrapped by a convenient C macro. In this way implementation is abstracted away from the client code
-2. struct definitions and free/init methods will be modified to implement the new feature
+1. all accesses to array elements could be wrapped by a convenient C macro.
+ In this way implementation is abstracted away from the client code
+2. struct definitions and free/init methods will be modified to implement
+ the new feature
3. the macro will be modified to suit the implementation at previous item
To implement item 1 we will use a perl pie like the following:
+
::
perl -pi -e "s/([mM])ap->layers\[(.*?)\]\]\./GET_LAYER(\1ap, \2\])->/g" *.c
@@ -268,34 +323,41 @@
perl -pi -e "s/src->layers\[(.*?)\]/GET_LAYER(src, \1)/g" *.c
and this is the macro that will be used:
+
::
#define GET_LAYER(map, pos) map->layers[pos]
-This will leave only very few occurrences (about 4 or 5) out that must be edited by hand. The same approach will be used with
-other arrays of structures (classes and styles).
+This will leave only very few occurrences (about 4 or 5) out that must be
+edited by hand. The same approach will be used with other arrays of
+structures (classes and styles).
This item has been implemented for the classes without using the GET_CLASS macro.
-3.4 Keep parent references and C internal structure in sync
+Keep parent references 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 parent reference 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*).
+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.
-The mapscript API will be backward compatible.
+Returning to the example of the layerObj the *insertClass*, *getClass* and
+*removeClass* methods will have to be modified to keep the parent reference
+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*).
-3.5 Destructors obey the reference counter
+The MapScript API will be backward compatible.
+
+Destructors obey the reference counter
++++++++++++++++++++++++++++++++++++++++++
-The various free* methods must check the counter before freeing memory. This will be implemented in the
-native code as in the following example:
+
+The various free* methods must check the counter before freeing memory.
+This will be implemented in the native code as in the following example:
+
::
void msFreeMap(mapObj *map) {
@@ -304,23 +366,29 @@
// go on destroying the object as usual
}
-This will ensure that children will not be freed in case the parent is garbage collected
-before them. To avoid that the parent attempts to double free some of its children:
+This will ensure that children will not be freed in case the parent is
+garbage collected before them. To avoid that the parent attempts to double
+free some of its children:
-a. if the parent is destroyed before its children the parent should NULLify its pointer in the children
+a. if the parent is destroyed before its children the parent should
+ NULLify its pointer in the children
-b. viceversa, when the children are GC'ed earlier than their parent, they must NULLify their pointers in the parent (we are evaluating whether this could ever happen once the parent reference is in place)
+b. viceversa, when the children are GC'ed earlier than their parent, they must
+ NULLify their pointers in the parent (we are evaluating whether this
+ could ever happen once the parent reference is in place)
-3.6 Always give object ownership to SWIG
+Always give object ownership to SWIG
++++++++++++++++++++++++++++++++++++++++
+
For the reference count to work all object ownership must be given to SWIG. This
is quite different from how it is today. The change however is straightforward
-because SWIG will acquire object ownership by default and is only a matter of removing
-all *%newobject* statements in the swig interface files.
+because SWIG will acquire object ownership by default and is only a matter of
+removing all *%newobject* statements in the swig interface files.
At the moment there are 58 *%newobject* statements.
C# must also change the following three lines in *csmodule.i*:
+
::
csharp/csmodule.i:375: if (map != null) this.swigCMemOwn = false;$excode
@@ -329,12 +397,14 @@
or drop the contructor customization altogether.
-3.7 JAVA: mapscript code example for layerObj
+JAVA: MapScript code example for layerObj
+++++++++++++++++++++++++++++++++++++++++++++
-Tamas has proposed a more object oriented approach to this problem, which can be adopted for those languages that support OOrientation.
+Tamas has proposed a more object oriented approach to this problem, which can
+be adopted for those languages that support OOrientation.
Code example for layerObj (*javamodule.i*):
+
::
/*
@@ -370,8 +440,9 @@
%}
-3.8 PERL: mapscript code example for layerObj
+PERL: MapScript code example for layerObj
+++++++++++++++++++++++++++++++++++++++++++++
+
Code example for layerObj (*plmodule.i*):
::
@@ -425,18 +496,19 @@
%}
-4. Implementation plan
+Implementation plan
----------------------
-It seems that for most mapscripts (java, csharp, perl and python) there
+
+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 to achieve 3.2.
-As of Tcl I currently don't know if it's possible.
+For ruby we'll probably have to go a different route and implement the
+*%trackobjects* feature to achieve 3.2. As of Tcl I currently don't know if it's possible.
-The two following section describe in detail the required SWIG-mapscript
+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 capabilites: %javacode
+Checking SWIG-Mapscript capabilites: %javacode
++++++++++++++++++++++++++++++++++++++++++++++++++
Swig provides the equivalent of *%javacode* for the following languages:
@@ -453,27 +525,34 @@
This swig construct will be used to inject in the wrapper the definition for
the references described in 3.2 and the wrapper methods.
-4.1 Checking SWIG-Mapscript capabilites: constructor customization
+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.
+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 behavior with
+*%pythonprepend* or *%pythonprepend* in python and with
+*%perlcode* or *%feature("shadow")* in perl.
This swig construct will be used to populate parent backreferences.
-4.2 Java and C-Sharp
+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 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 or be based on the proposal made by Tamas in the last discussion thread.
+The implementation should follow exactly this RCF or be based on the proposal
+made by Tamas in the last discussion thread.
-*Note* : as of Jan 2008 Tamas decided to write his own implementation of RFC24 for C#
+.. note::
+
+ as of Jan 2008 Tamas decided to write his own implementation of
+ :ref:`rfc24` for C#
-4.3 Perl
+Perl
++++++++
As in the example above most of the perl customization can be done
@@ -481,43 +560,48 @@
The implementation will follow this RFC exactly.
-4.4 Python
+Python
++++++++++
-Python enjoys first-grade support in SWIG so the RFC should be implemented exactly
-as described.
-4.5 Ruby
+Python enjoys first-grade support in SWIG so the RFC should be implemented
+exactly as described.
+
+Ruby
++++++++
Needs investigation, probably we'll have to use rb_gc_* funtions to mark objects
and prevent their garbage collection or use *%trackobjects*.
Ruby will not implement this RFC as of item 3.2.
-4.6 Tcl
+Tcl
+++++++
Needs investigation and a Tcl expert.
-At the time of this writing Tcl will probably not implement this RFC as of item 3.2.
+At the time of this writing Tcl will probably not implement this RFC
+as of item 3.2.
-4.7 PHP
+PHP
+++++++
-PHP mapscript does not rely on SWIG, but since most of the code is native it should be
+PHP MapScript does not rely on SWIG, but since most of the code is native it should be
possibile to adopt this RFC.
-5.1 Implementation checklist
+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 mantainer will populate the relative cell with one of the following
-marks:
+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 the child->parent reference has been implemented
-- a plus sign (+) if object has had the reference counter increased (under the CNT=Counter column)
+- a plus sign (+) if object has had the reference counter increased
+ (under the CNT=Counter column)
-- a minus sign (-) if object has had the reference counter decreased (under the CNT=Counter column)
+- a minus sign (-) if object has had the reference counter decreased
+ (under the CNT=Counter column)
-- =1 if the reference counter has been reset to 1 (under the CNT=Counter column)
+- =1 if the reference counter has been reset to 1
+ (under the CNT=Counter column)
-5.2 mapObj
+mapObj
++++++++++
===================== ======= ============= ============ ============ ============= ========== =============
@@ -557,7 +641,7 @@
clone =1
===================== ======= ============= ============ ============ ============= ========== =============
-5.3 layerObj
+layerObj
++++++++++++
======================= ======= ============= ============ ============ ============= ========== =============
@@ -580,7 +664,7 @@
getExtent
======================= ======= ============= ============ ============ ============= ========== =============
-5.4 classObj
+classObj
++++++++++++
======================= ======= ============= ============ ============ ============= ========== =============
@@ -598,7 +682,7 @@
removeStyle \-
======================= ======= ============= ============ ============ ============= ========== =============
-5.5 webObj
+webObj
++++++++++
======================= ============= ============ ============ ============= ========== =============
@@ -611,8 +695,9 @@
getMetadata
======================= ============= ============ ============ ============= ========== =============
-5.5 styleObj
+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.
@@ -633,8 +718,9 @@
clone =1
======================= ======= ============= ============ ============ ============= ========== =============
-5.6 labelObj
+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.
@@ -654,8 +740,9 @@
getBackgroundshadowcolor
========================== ============= ============ ============ ============= ========== =============
-5.7 hashTableObj
+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.
@@ -665,8 +752,9 @@
hashTableObj (constructor)
========================== ============= ============ ============ ============= ========== =============
-5.8 colorObj
+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.
@@ -676,8 +764,9 @@
colorObj (constructor)
========================== ============= ============ ============ ============= ========== =============
-5.9 imageObj
+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.
@@ -687,8 +776,9 @@
imageObj (constructor)
========================== ============= ============ ============ ============= ========== =============
-5.10 shapeObj
+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.
@@ -712,8 +802,9 @@
symDifference
========================== ============= ============ ============ ============= ========== =============
-5.11 lineObj
+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.
@@ -727,8 +818,9 @@
set
========================== ============= ============ ============ ============= ========== =============
-5.12 pointObj
+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.
@@ -739,8 +831,9 @@
toShape
========================== ============= ============ ============ ============= ========== =============
-5.13 symbolsetObj
+symbolsetObj
+++++++++++++++++
+
For symbolsetObjs it is not necessary to add the reference pointing back to the map.
========================== ======= ============= ============ ============ ============= ========== =============
@@ -756,8 +849,9 @@
removeSymbol \-
========================== ======= ============= ============ ============ ============= ========== =============
-5.14 symbolObj
+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.
@@ -771,32 +865,39 @@
setImage
========================== ======= ============= ============ ============ ============= ========== =============
-6. Open issues
+Open issues
--------------
-The following issues should be discussed after this rfc has been adopted/implemented.
+The following issues should be discussed after this RFC has been
+adopted/implemented.
-6.1 Multiple owners for an object
+Multiple owners for an object
+++++++++++++++++++++++++++++++++
-It is the case of layer that is added to more than one map. This should be prohibited
-because the layer has only one parent reference.
-On insertion the code should check whether the C parent reference is not null and in that
-case raise a *errorObj* which will be transformed by the hosting language in an exception.
-Workaround: the user should instead clone the object and the add the clone to the second map.
+It is the case of layer that is added to more than one map. This should
+be prohibited because the layer has only one parent reference. On insertion
+the code should check whether the C parent reference is not null and in that
+case raise a *errorObj* which will be transformed by the hosting language
+in an exception.
-7. API Compatibility
+Workaround: the user should instead clone the object and the add the clone
+to the second map.
+
+API Compatibility
--------------------
-It is a top priority of this RFC to preserve the investment made by mapscript users by mantaining the API backwards compatible in both terms of method signatures and usage (i.e. order of invocation, types, return codes, etc).
+It is a top priority of this RFC to preserve the investment made by MapScript
+users by maintaining the API backwards compatible in both terms of method
+signatures and usage (i.e. order of invocation, types, return codes, etc).
-If there will be any exception to this rule it will have to be justified and be described under this section.
+If there will be any exception to this rule it will have to be justified
+and be described under this section.
-7. Status
+Status
---------
RFC opened for comments on Jan, the 10th 2007 with a post on mapserver-dev.
RFC undergoing revision after discussion on mapserver-dev.
-New revision published on mapserver web.
+New revision published on MapServer web.
RFC adopted with voting closed on April 4, 2007:
@@ -804,9 +905,9 @@
+0: Frank Warmerdam
-8. Activity
+Activity
-----------
-The bug#2032 will be used to track activity related to this rfc.
+The `bug #2032`_ will be used to track activity related to this RFC.
2/20/2007: attached patch that converts map->layers in array of pointers with dynamic allocation (item 3.3)
@@ -817,3 +918,4 @@
1/10/2008: RFC implementation completed
+.. _bug #2032: http://trac.osgeo.org/mapserver/ticket/2032
More information about the mapserver-commits
mailing list