klib Directory Reference

Directories
directory	include
directory	src
Files
file	doxygen.h [code]

---

Detailed Description

Overview

klib is an object-oriented C library which provides various classes and methods of general utility -- lists and arrays, variable-length unicode strings, filesystem path processing, etc.

Inheritance

klib uses a simple, C-language method of inheritance. Each object is defined as a struct, and subclasses include in their own structs the complete struct of the base class. This works because we know how data is packed into structs, at least with common compilers. Because we know how big each struct is, we can always fine the structs corresponding to the base classes from within the derived classes.

So, for example, we have:

typedef struct _klib_Object
  {
  // Fields for the Object class
  } klib_Object

typedef struct _klib_String
  {
  // The base class
  struct klib_Object;
  // Fields for the string class
  } klib_Object

Each class is expected to initialize the value of the 'name' field in klib_Object, so that rudimentary run-time type checking can be done.

By convention each object is named by a struct, whose name begins with an underscore, and a defined type with the same name without the underscore.

Polymorphic methods are implemented by keeping a pointer to the method in the class struct, and implementing a method that calls the function via the pointer. Subclasses can change the pointer to point to their own implementations.

Construction

Conventionally, the low-level construction of the object is done in a function whose name is [object_name]_construct, which takes as a minimum a pointer to a newly-allocated block of memory, and enough arguments to initialize the object. Clients usually create new objects by calling one of the [object_name]_new() methods, which call the constructor with the appropriate arguments. This two-stage process is not strictly necessary, but it makes it easy to implement different forms of _new() method without duplicating code. One operation the constructor always carries out is to set the pointers to polymorphic methods; _dispose must be set, and _to_string should be set.

Reference counting and disposal

klib implements a simple form of garbage collection using reference counts. Each object has a reference count, which can be incremented and decremented using klib_object_add_ref and klib_object_unref respectively. When the reference count reaches zero, the corresponding _dispose method is called to tidy up the object. Because the implementation may call dispose more than once for a given object, implementations must ensure that they have some way to prevent this have adverse side effects. Typically we create a property called 'disposing', which is set to TRUE only once the destructor _dispose is entered. If disposing is aleady TRUE, the _dipose method takes no action.

Increasing references is much faster than cloning objects, although of course callers must be aware that they could be holding a reference to an object that is shared by many classes. Nearly all klib methods that take a reference to a klib object will add a reference, so the caller need not refrain from freeing it as soon as it likes.

Objects should be freed by calling klib_object_unref; callers should never have to interact with destructors directly.