Subclassing List Class - Revision history

Krashan: /* Example constructor */

2012-05-22T08:50:18Z

‎Example constructor

Krashan: /* Example Destructor */

2012-05-22T08:49:44Z

‎Example Destructor

Krashan: /* Compound Data Items, Multicolumn Lists */ Destructor

2012-05-22T08:39:08Z

‎Compound Data Items, Multicolumn Lists: Destructor

Krashan: /* Compound Data Items, Multicolumn Lists */ Constructor.

2012-05-22T08:23:00Z

‎Compound Data Items, Multicolumn Lists: Constructor.

Krashan: /* To Copy Or Not to Copy? */ Style.

2012-02-16T19:05:04Z

‎To Copy Or Not to Copy?: Style.

Krashan: /* Compound Data Items, Multicolumn Lists */ Fixed typo.

2012-02-16T19:01:09Z

‎Compound Data Items, Multicolumn Lists: Fixed typo.

Krashan: /* To Copy Or Not to Copy? */

2012-02-06T13:44:28Z

‎To Copy Or Not to Copy?

Krashan: /* To Copy Or Not to Copy? */

2012-02-06T13:03:47Z

‎To Copy Or Not to Copy?

Krashan: /* To Copy Or Not to Copy? */

2012-02-06T11:44:31Z

‎To Copy Or Not to Copy?

Krashan: /* Compound Data Items, Multicolumn Lists */

2012-02-06T11:12:59Z

‎Compound Data Items, Multicolumn Lists

@@ Line 214: / Line 214: @@
         return (IPTR)idata;
+      }
       FreeTaskPooled(idata, sizeof(struct InternalData));
+    }

@@ Line 224: / Line 224: @@
 ==Example Destructor==
-The only task of our destructor is to free memory areas allocated in the constructor. Note the order of deallocation, ''ItemName'' is freed first. If we freed the ''InternalData'' structure first, the pointer to item name would be in free memory and as such could be overwritten before we manage to free it as well. The constructor uses step-down order of construction, it allocates the item first and then its components. The destructor is symmetrical, so it frees components first, then the item.
+The only task of our destructor is to free memory areas allocated in the constructor. Note the order of deallocation, ''ItemName'' is freed first. If we freed the ''InternalData'' structure first, the pointer to item name would be in free memory and as such could be overwritten before we manage to free it as well. The constructor uses step-down order of construction, it allocates the item first and then its components. The destructor is symmetrical, so it frees components first, then the item. Because I've made sure in the constructor, that ''Internal Data'' is always fully constructed, I do not need to check pointers  to components against ''NULL'' value.
   IPTR ListDestruct(Class *cl, Object *obj, struct MUIP_List_Destruct *msg)

@@ Line 200: / Line 200: @@
 We have just opted for full copying constructor. The code of it is simple:
-  IPTR ListConstruct(UNUSED Class *cl, UNUSED Object *obj, struct MUIP_List_Construct *msg)
+  IPTR ListConstruct(Class *cl, Object *obj, struct MUIP_List_Construct *msg)
+  {
     struct InputData *entry = (struct InputData*)msg->entry;
@@ Line 217: / Line 217: @@
       FreeTaskPooled(idata, sizeof(struct InternalData));
+    }
     return NULL;
+  }
 The code does not use a memory pool provided by the ''List'' class. Instead it uses modern MorphOS specific functions allocating from memory pool assigned to every system process. This pool is automatically disposed when a process terminates. Care should be taken to not return a half-constructed list item. Every allocation is checked, and if the second one, which allocates space for the item name string, fails, item structure is freed and constructor returns ''NULL''. Numeric values are converted to numbers with standard ''atof()'' call. If allocations have been succesfull, a newly created and filled ''InternalData'' structure is returned.

← Older revision		Revision as of 08:23, 22 May 2012
Line 196:		Line 196:

	The item constructor will take a pointer to ''InputData'', allocate ''InternalData'', create a copy of ''ItemName'' and convert ''Quantity'' and ''Price''.		The item constructor will take a pointer to ''InputData'', allocate ''InternalData'', create a copy of ''ItemName'' and convert ''Quantity'' and ''Price''.
		+
		+	==Example constructor==
		+	We have just opted for full copying constructor. The code of it is simple:
		+
		+	IPTR ListConstruct(UNUSED Class cl, UNUSED Object obj, struct MUIP_List_Construct *msg)
		+	{
		+	struct InputData entry = (struct InputData)msg->entry;
		+	struct InternalData *idata;
		+
		+	if (idata = AllocTaskPooled(sizeof(struct InternalData)))
		+	{
		+	if (idata->ItemName = AllocVecTaskPooled(strlen(entry->ItemName) + 1))
		+	{
		+	strcpy(idata->ItemName, entry->ItemName);
		+	idata->Quantity = atof(entry->Quantity);
		+	idata->Price = atof(entry->Price);
		+	return (IPTR)idata;
		+	}
		+
		+	FreeTaskPooled(idata, sizeof(struct InternalData));
		+	}
		+
		+	return NULL;
		+	}
		+
		+	The code does not use a memory pool provided by the ''List'' class. Instead it uses modern MorphOS specific functions allocating from memory pool assigned to every system process. This pool is automatically disposed when a process terminates. Care should be taken to not return a half-constructed list item. Every allocation is checked, and if the second one, which allocates space for the item name string, fails, item structure is freed and constructor returns ''NULL''. Numeric values are converted to numbers with standard ''atof()'' call. If allocations have been succesfull, a newly created and filled ''InternalData'' structure is returned.

@@ Line 175: / Line 175: @@
 These cases are only examples, as the real life often gets even more complicated...
-When there is a need to create a copy of some data inside ''MUIM_List_Construct()'', the ''List'' class helps with memory management by providing automatically created [[Memory Pools|memory pool]]. Using it is by no mean obligatory. On classic Amiga systems pooled memory allocations were substantially faster, but it is not the case on MorphOS. An advantage of using pooled allocations is a possibility to skip implementation of item destructor (''MUIM_List_Destruct()''), as the pool is freed automatically when the list object is disposed. For very long lists (thousands of items and more) freeing just the pool is also much faster than freeing individual allocations. On the other hand skipping the item destructor may be dangerous for programs adding and removing items continuously, as they will be consuming more and more memory, which will not be freed until a program is terminated.
+When there is a need to create a copy of some data inside ''MUIM_List_Construct()'', the ''List'' class helps with memory management by providing automatically created [[Memory Pools|memory pool]]. Using it is not mandatory however. On classic Amiga systems pooled memory allocations were substantially faster, but it is not the case on MorphOS. An advantage of using pooled allocations is a possibility to skip implementation of item destructor (''MUIM_List_Destruct()''), as the pool is freed automatically when the list object is disposed. For very long lists (thousands of items and more) freeing just the pool is also much faster than freeing individual allocations. On the other hand skipping the item destructor may be dangerous for programs adding and removing items continuously, as they will be consuming more and more memory, which will not be freed until a program is terminated.
 Armed with all this knowledge, one can attempt to implement an example item constructor. A list object will be showing a warehouse inventory. Input data structure is a set of dynamically created strings, for example fetched from a remote database:

@@ Line 164: / Line 164: @@
 * '''''MUIM_List_Destruct''''' &ndash; the method is called when an item is removed (or the object is disposed, which implies removing all items first). The item destructor frees any resources allocated in constructor for an item. It usually means freeing memory buffers allocated for copies of dynamic data. The default implementation of this method does nothing.
 * '''''MUIM_List_Display''''' &ndash; converts internal data representation to a set of strings to be displayed in list columns. The default implementation assumes internal data is a text string, which is passed through to be displayed in the first (and only) column.
-* '''''MUIM_List_Compare''''' &ndash; compares two internal data structures. This method is used only for list sorting and sorted inserts. The class uses it as a comparision callback for ''quicksort'' algorithm. The method need not to be implemented if sorting is not needed. The default implementation assumes it gets pointer to two text strings and calls ''stricmp()'' on them.
+* '''''MUIM_List_Compare''''' &ndash; compares two internal data structures. This method is used only for list sorting and sorted inserts. The class uses it as a comparision callback for ''quicksort'' algorithm. The method need not to be implemented if sorting is not needed. The default implementation assumes it gets pointers to two text strings and calls ''stricmp()'' on them.
 <small>'''Note:''' Older versions of MUI implemented these four methods as callbacks using [[Hook|hooks]]. These hooks were set via attributes documented in the ''List'' class autodoc. Hooks still work for backward compatibility, but are not recommended in new code, especially as dealing with them on MorphOS is a bit cumbersome. The only useful exception is builtin copying string constructor and destructor. We have used them in the third example above.</small>

← Older revision		Revision as of 13:03, 6 February 2012
Line 174:		Line 174:
	* List is a view of very large (let's say several gigabytes) dataset stored on disk. Data rows are loaded on demand inside ''MUIM_List_Display()'' then. In this case data are in fact never inserted, as the internal data structure will only contain, for example, offset in a file.		* List is a view of very large (let's say several gigabytes) dataset stored on disk. Data rows are loaded on demand inside ''MUIM_List_Display()'' then. In this case data are in fact never inserted, as the internal data structure will only contain, for example, offset in a file.
	These cases are only examples, as the real life often gets even more complicated...		These cases are only examples, as the real life often gets even more complicated...
		+
		+	When there is a need to create a copy of some data inside ''MUIM_List_Construct()'', the ''List'' class helps with memory management by providing automatically created [[Memory Pools\|memory pool]]. Using it is by no mean obligatory. On classic Amiga systems pooled memory allocations were substantially faster, but it is not the case on MorphOS. An advantage of using pooled allocations is a possibility to skip implementation of item destructor (''MUIM_List_Destruct()''), as the pool is freed automatically when the list object is disposed. For very long lists (thousands of items and more) freeing just the pool is also much faster than freeing individual allocations. On the other hand skipping the item destructor may be dangerous for programs adding and removing items continuously, as they will be consuming more and more memory, which will not be freed until a program is terminated.
		+
		+	Armed with all this knowledge, one can attempt to implement an example item constructor. A list object will be showing a warehouse inventory. Input data structure is a set of (dynamically created) strings:
		+
		+	struct InputData
		+	{
		+	STRPTR ItemName;
		+	STRPTR Quantity;
		+	STRPTR Price;
		+	};
		+
		+	For internal representation, we prefer to convert numerical data to double precision floating point numbers, which will make any further computations easier:
		+
		+	struct InternalData
		+	{
		+	STRPTR ItemName;
		+	DOUBLE Quantity;
		+	DOUBLE Price;
		+	};
		+
		+	The item constructor will take a pointer to ''InputData'', allocate ''InternalData'', create a copy of ''ItemName'' and convert ''Quantity'' and ''Price''.

← Older revision		Revision as of 11:44, 6 February 2012
Line 168:		Line 168:

	==To Copy Or Not to Copy?==		==To Copy Or Not to Copy?==
−	The title question is one of the most important design decisions to take when one subclasses the ''List'' class.	+	The title question is one of the most important design decisions to take when one subclasses the ''List'' class. The main, obvious rule is that all item data must exist while the item is on the list. If it cannot be ensured, the item constructor has to create copies, which are later free in destructor. In most cases "copy" is the right choice, except of some special cases like:
		+	* Fixed (for example hardcoded) set of data, a rare case, but happens sometimes.
		+	* List is only a view of data stored elsewhere in the application, duplicating makes no sense.
		+	* There are multiple lists or data views sharing the same dataset which may be updated. While having non-copying constructor in this case avoids reinserting item in multiple lists, all the lists must be manually refreshed after update anyway.
		+	* List is a view of very large (let's say several gigabytes) dataset stored on disk. Data rows are loaded on demand inside ''MUIM_List_Display()'' then. In this case data are in fact never inserted, as the internal data structure will only contain, for example, offset in a file.
		+	These cases are only examples, as the real life often gets even more complicated...

@@ Line 161: / Line 161: @@
 * '''displayed content''' is a set of strings (one per list column) which are to be displayed. These strings may contain control codes for styles, colors and inline images.
 There are four methods in the ''List'' class to be overloaded. They deal with the three data kinds in the way depicted on the diagram and explained below:
-* '''''MUIM_List_Construct''''' &ndash; the method is called when an item is inserted to the list. It gets a pointer to input data structure and converts it somehow into an internal data structure. Then this internal data structure is inserted into a list. The default implementation of this method just passes through the received pointer. It may be the right thing to do, when data are static and slimple. Two first examples in this article used the default item constructor. A typical task of the constructor is to create copies of dynamic data, it may also strip unused data off the input data structure or perform some conversions.
+* '''''MUIM_List_Construct''''' &ndash; the method is called when an item is inserted to the list. It gets a pointer to input data structure and converts it somehow into an internal data structure. Then this internal data structure is inserted into a list. The default implementation of this method just passes through the received pointer. It may be the right thing to do, when data are static and simple. Two first examples in this article used the default item constructor. A typical task of the constructor is to create copies of dynamic data, it may also strip unused data off the input data structure or perform some conversions.
 * '''''MUIM_List_Destruct''''' &ndash; the method is called when an item is removed (or the object is disposed, which implies removing all items first). The item destructor frees any resources allocated in constructor for an item. It usually means freeing memory buffers allocated for copies of dynamic data. The default implementation of this method does nothing.
 * '''''MUIM_List_Display''''' &ndash; converts internal data representation to a set of strings to be displayed in list columns. The default implementation assumes internal data is a text string, which is passed through to be displayed in the first (and only) column.
 * '''''MUIM_List_Compare''''' &ndash; compares two internal data structures. This method is used only for list sorting and sorted inserts. The class uses it as a comparision callback for ''quicksort'' algorithm. The method need not to be implemented if sorting is not needed. The default implementation assumes it gets pointer to two text strings and calls ''stricmp()'' on them.