molib documentation

Languages Available: français español

CLASS

moBase

NAME

Constructor - initialize an moBase object
Destructor - ensure that an moBase object can be deleted
Copy operator - initialize an moBase object
assignment operator - copy an moBase object in another
new operator - allocates a buffer for a new object
delete operator - frees a buffer of an object

VERSION

Version: 1.2.0

SYNOPSIS

moBase(void);
virtual ~moBase();

moBase(const moBase& object);
moBase& operator = (const moBase& object);

void *operator new(size_t size);
void operator delete(void *object);

DESCRIPTION

The moBase class object is always constructed without parameters. It gives the new objects a unique serial number and increase the internal serial number counter.

The destructor doesn't do anything at this time. However, it was made virtual so virtual objects can still use this base object.

The error numbers are also defined within this object. This way all the errors are common to all objects. The moError(3) object can use these error numbers. The following is the current list:

MO_ERROR_UNDEFINED used as a default number (it is zero) when no specific error number was defined for an error

MO_ERROR_MEMORY any time a memory error occurs, use this error number with a: throw std::bad_alloc; You should never use this error with an moError() object unless you were trying to allocate a really large buffer (several megabytes)

MO_ERROR_COMPARE the Compare() function failed for some reasons and generated an error

MO_ERROR_UNORDERED the Compare() function has been applied on objects which can't be ordered properly

MO_ERROR_BAD_COMPARE the Compare() function returned an invalid value

MO_ERROR_UNKNOWN something made the software generate an error; we don't know what though

MO_ERROR_OVERFLOW something's full or too large

MO_ERROR_UNDERFLOW something's empty or too small

The user can also declare his own errors with the use of the MO_ERROR_USER_NUMBER macro. The following is an example:

#define GD_ERROR_MISSING_CHAPTER (MO_ERROR_USER_NUMBER + 0) #define GD_ERROR_INVALID_CHAPTER (MO_ERROR_USER_NUMBER + 1)

NOTES

The serial number of an moBase object is assigned at the time it is constructed and is unique until over 4 billion objects are created in the same program instance.

Whenever you compile with the MO_THREAD define, the serial number is managed in a multi-thread safe way.

SEE ALSO

Serial(), Compare(), operator ==, operator !=, operator <, operator <=, operator >, operator >=

BUGS

You have to watch out! The reference count of an object is initialized to 1 whenever it isn't dynamic and 0 when it is dynamic. The destructor which always check to know whether the exact reference count is present in your objects.

The fact is that a new operator is not supposed to create a referenced object however, a stack object is referenced by the stack and a variable member is referenced by its parent (the object which contains that variable member).

The result is that you can write the following code and it all works fine as long as the AddRef() and Release() do match:

Foo *foo;

foo = new Foo; ... delete foo;

Or with smart pointers (i.e. exception safe):

FooSPtr foo;

foo = new Foo; ...

Note that with the smart pointer you don't want to delete the object, instead the smart pointer will release it whenever the pointer (FooSPtr here) is being destroyed. This will have the effect of destroying foo as well.

It is strongly adviced that you always use Smart Pointers except in a very few exceptional cases. Smart pointers ensure that you get allocated objects released whenever return statements or throws are encountered.

COPYRIGHTS

This documentation and the code being documented is proprietary and cannot be duplicated without the express and written consent of Made to Order Software Coporation.

Copyright (c) 1999-2007 by Made to Order Software Corporation
All rights reserved.

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moBase

NAME

Serial - return the serial number of an object

VERSION

Version: 1.2.0

SYNOPSIS

moAtomicWord Serial(void) const;

DESCRIPTION

All objects created from an moBase object will receive a unique serial number. That number can be retrieved using the Serial() function.

Note that the serial number is unique among all the objects of a binary instance. It is not unique among the whole running operating system.

RETURN VALUE

Serial returns a uint64_t unique number.

SEE ALSO

Constructor

BUGS

At this time, in a multi-thread environment, the serial number may not be unique. This is a problem in the constructor.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moBase

NAME

IsDynamicObject - return true if the object was not allocated with new

VERSION

Version: 1.2.0

SYNOPSIS

bool IsDynamicObject(void) const;

DESCRIPTION

This function returns the dynamic flag. Whenever an object is allocated using the new operator, then it is considered dynamic. This means it can safely use the AddRef() and Release() functions to fully manage the object.

To the contrary, objects either allocated on the stack or which are part of another object (say, a variable member of moWCString type will be viewed as a non-dynamic object).

A non-dynamic object can still be AddRef()'ed and Release()'d however, it won't be freed with the last Release().

Note that if you create an object on the stack and give it to another which saves a pointer to it in a smart pointer, then return from your current function (meaning that the objects on the stack will be destroyed) would normally generate a dangling pointer. With this system, in debug we detect such errors and break the program at the time the destructor is hit since it will know that some other object need this object. Unfortunatly, there isn't much we can do in release mode other than generate an exception.

NOTES

This function works even when the object pointer is NULL. This is useful in case you use an moSmartDynamicPtr.

RETURN VALUE

true when the object is truely dynamic

SEE ALSO

Constructor, Destructor, AddRef, Release

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moBase

NAME

GetClassName - get the name of an moBase derived object

VERSION

Version: 1.2.0

SYNOPSIS

virtual const char *GetClassName(void) const;

DESCRIPTION

This function is expected to be overloaded in any object derived from the moBase.

RETURN VALUE

A pointer to a static string.

SEE ALSO

Constructor, Destructor, AddRef, Release

BUGS

This is a virtual function and thus it won't work on null pointer nor from within a constructor. The latter will not recognize the full scope of the class, but it at least won't crash.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moBase

NAME

SizeOf - return the amount of currently allocated memory of this object

VERSION

Version: 1.2.0

SYNOPSIS

virtual size_t SizeOf(void) const;

DESCRIPTION

This function is expected to be overloaded in any object derived from the moBase and to return the exact amount of bytes allocated by the object.

The total needs to include a sizeof() of the object and the total SizeOf() of each sub-object and mo_malloc() objects. In case a system object is allocated (i.e. a FILE when you call fopen() for instance), you want to try to return the size of that object.

Note that whenever an object includes sub-objects (i.e. moFile includes an moWCString), it needs to call the SizeOf() of that object and subtracts the sizeof() of the object since it will be included in the returned value.

The purpose of this function is only to be informative. Thus, if an object SizeOf() function isn't implemented, it is just fine. The size will of course be wrong in that case.

The main idea behind creating such a function is to be able to know the total amount of memory allocated at a given point in time. This can be useful for different debugging tasks.

RETURN VALUE

The number of bytes allocated.

SEE ALSO

GetClassName

BUGS

The value returned is likely wrong if the object didn't properly implement its own SizeOf() function!

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moBase

NAME

AddRef - add one to the reference counter of the object
Release - substract one to the reference counter of the object
ReferenceCount - return the current value of the object reference counter

VERSION

Version: 1.2.0

SYNOPSIS

unsigned long AddRef(void) const;
unsigned long Release(void);
unsigned long ReferenceCount(void) const;

DESCRIPTION

Any object derived from moBase beneficiates of a reference counter. This counter can be used to know how many objects reference the object at a given time. When the last user calls Release(), the counter reaches 0 and the object deletes itself.

It is possible to check out the reference counter using the ReferenceCount() function.

The AddRef() should be called every time you make a copy of the object pointer. The Release() function will be called once you don't need that pointer any more. The following is the proper use of the calls when you are replacing a pointer by another. This ensures that if ptr == f_ptr everything works fine.

ptr->AddRef(); f_ptr->Release(); f_ptr = ptr;

All of these function calls are not virtual and thus work with NULL pointers.

NOTES

The Release() is not marked as const because it may delete the object.

When Release() returns 0, you know that the object was deleted.

RETURN VALUE

The current counter or the counter after the function was
applied. If the object pointer is NULL, 0 is returned.

SEE ALSO

Constructor

BUGS

At this time, in a multi-thread environment, counters will be wrong (they are not yet protected).

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moBase

NAME

Comparisons -- compare moBase objects between each others

VERSION

Version: 1.2.0

SYNOPSIS

moBase::compare_t Compare(const moBase& object) const;
static compare_t CompareInt(int a, int b) const;
static compare_t CompareUInt(unsigned int a, unsigned int b) const;

bool operator == (const moBase& object) const;
bool operator != (const moBase& object) const;
bool operator < (const moBase& object) const;
bool operator <= (const moBase& object) const;
bool operator > (const moBase& object) const;
bool operator >= (const moBase& object) const;

private:
compare_t OperatorCompare(const moBase& object) const;

PARAMETERS

object - object to compare with this
a - the left hand side integer
b - the right hand side integer

DESCRIPTION

The moBase class object has a compare function so all objects which the inherit moBase class can be compared against any other object which also inherit the moBase class.

When no compare function is declared in an object, then it will be considered as an object which can't be ordered.

The compare function must return one of the following value:

MO_BASE_COMPARE_ERROR an error occured while doing the comparison

MO_BASE_COMPARE_SMALLER 'this' is smaller than 'object'

MO_BASE_COMPARE_EQUAL the two objects are equal

MO_BASE_COMPARE_GREATER 'this' is larger than 'object'

MO_BASE_COMPARE_UNORDERED these two objects can't be compared (there is no solution)

Whenever you are comparing two integers (signed or not) you can use the CompareInt() or CompareUInt() functions instead of re-writing the same comparison over and over again.

The usual equality, inequality and order operators are all programmed with a call to the Compare() function. The equality will quickly test whether 'this' == 'object'. If true, it will return true right away. When any of the operators receives MO_BASE_COMPARE_ERROR or MO_BASE_COMPARE_UNORDERED as a result, a throw is generated. The following shows you which throw is used by OperatorCompare(): MO_BASE_COMPARE_ERROR throw long(MO_ERROR_COMPARE); MO_BASE_COMPARE_UNORDERED throw long(MO_ERROR_UNORDERED); <invalid result> throw long(MO_ERROR_BAD_COMPARE);

The understood operators are:

operator == operator != operator < operator >= operator > operator <=

NOTES

Some objects, such as the moString, may have extraneous compare functions such as CompareNoCase() which will compare two strings together without taking the case in account. There is no support for these in the base object since the point was to enable all the operators (==, !=, <, <=, >, >=) to function without having to redefine them in each single object. These operators can't be used for extraneous compares anyway.

BUGS

It is usually not true that any object can be compared with any object. The compare is rather intended to compare objects of the same type. The main idea is to avoid redefining the generic comparison operators (==, !=, <, <=, >, >=) since all of these can be computed from the result of Compare().

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

NAMESPACE

molib::Ptr

CLASS

moAnyPtr
moDynamicPtr
moStaticPtr

NAME

CheckPtr - ensure a pointer is dynamic or static or either

VERSION

Version: 1.2.0

SYNOPSIS

static void CheckPtr(const moBase *ptr);

PARAMETERS

ptr - a pointer to an object

DESCRIPTION

It is at times necessary to know whether a pointer is either dynamic or static.

The moSmartPtr class uses these three classes in order to ensure that the pointers in use are dynamic, static or either.

A dynamic pointer is a pointer to an object which was allocated on the heap. This happens when the object is created using the new operator opposed to being created either on the stack or as part of another object variable member.

You can use these classes to make sure a pointer is of a certain type as follow:

Foo(Foo *foo) { Ptr::moDynamicPtr::CheckPtr(foo) ... }

And this is similar to asserting that the object is dynamic as in:

Foo(Foo *foo) { assert(foo->IsDynamicObject()); }

but it can be used in a template which is why they exist.

SEE ALSO

moBase::operator new (), moBase::AllocObject(), moBase::FreeObject(), moBase::IsDynamic()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

Links:
molib
the sandbox