Class.h File Reference

Classes describe the state and behavior of an Objectively type. More...

#include <Objectively/Types.h>
#include <Objectively/Once.h>

Go to the source code of this file.

Data Structures
struct	Class
	The runtime representation of a Class. More...
struct	ClassDef
	ClassDefs are passed to _initialize via an archetype to initialize a Class. More...

Macros
#define	alloc(type)    ((type *) _alloc(_##type()))
	Allocate and initialize and instance of type.
#define	cast(type, obj)    ((type *) _cast(_##type(), (const ident) obj))
	Safely cast obj to type.
#define	classnameof(obj)    classof(obj)->def.name
	Resolve the Class name of the given Object instance.
#define	classof(obj)    ((Object *) obj)->clazz
	Resolve the Class of an Object instance.
#define	instanceof(type, obj)    (isobject(obj) && $((Object *) obj, isKindOfClass, _##type()))
	Test if the given pointer is an instance of the specified type.
#define	interfaceof(type, clazz)    ((type##Interface *) (clazz)->interface)
	Resolve the typed interface of a Class.
#define	isobject(obj)    (obj && *((unsigned int *) obj) == OBJECTIVELY_MAGIC)
	Test if the given pointer is an Object.
#define	obj
#define	OBJECTIVELY_MAGIC   0xdeadbeef
	The header value identifying Objectively types.
#define	super(type, obj, method, ...)    interfaceof(type, _Class()->def.superclass)->method(cast(type, obj), ## __VA_ARGS__)
#define	type

Functions
OBJECTIVELY_EXPORT ident	_alloc (Class *clazz)
	Instantiate a type through the given Class.
OBJECTIVELY_EXPORT ident	_cast (const Class *clazz, const ident obj)
	Perform a type-checking cast.
OBJECTIVELY_EXPORT Class *	_initialize (const ClassDef *clazz)
	Initializes the given Class.
OBJECTIVELY_EXPORT void	addClassImage (ident handle)
	Registers an image that provides Classes, e.g. a plugin.
OBJECTIVELY_EXPORT Class *	classForName (const char *name)
OBJECTIVELY_EXPORT ident	release (ident obj)
	Atomically decrement the given Object's reference count. If the resulting reference count is 0, the Object is deallocated.
OBJECTIVELY_EXPORT void	removeClassImage (ident handle)
	Unregisters an image, and every Class it declared.
OBJECTIVELY_EXPORT ident	retain (ident obj)
	Atomically increment the given Object's reference count.

Variables
OBJECTIVELY_EXPORT size_t	_pageSize
	The page size, in bytes, of the target host.

Detailed Description

Classes describe the state and behavior of an Objectively type.

Definition in file Class.h.

Macro Definition Documentation

alloc

#define alloc

(

type

)

((type *) _alloc(_##type()))

Allocate and initialize and instance of type.

Definition at line 222 of file Class.h.

   { \
    typeof(obj) _obj = obj; \
    _obj->interface->method(_obj, ## __VA_ARGS__); \
  })
 
#define $$(type, method, ...) \
  ({ \
    interfaceof(type, _##type())->method(__VA_ARGS__); \
  })
 
#define super(type, obj, method, ...) \
  interfaceof(type, _Class()->def.superclass)->method(cast(type, obj), ## __VA_ARGS__)

cast

#define cast	(		type,
			obj
	)		((type *) _cast(_##type(), (const ident) obj))

Safely cast obj to type.

Definition at line 228 of file Class.h.

classnameof

#define classnameof

(

obj

)

classof(obj)->def.name

Resolve the Class name of the given Object instance.

Definition at line 240 of file Class.h.

classof

#define classof

(

obj

)

((Object *) obj)->clazz

Resolve the Class of an Object instance.

Definition at line 234 of file Class.h.

instanceof

#define instanceof	(		type,
			obj
	)		(isobject(obj) && $((Object *) obj, isKindOfClass, _##type()))

Test if the given pointer is an instance of the specified type.

Definition at line 216 of file Class.h.

interfaceof

#define interfaceof	(		type,
			clazz
	)		((type##Interface *) (clazz)->interface)

Resolve the typed interface of a Class.

Definition at line 246 of file Class.h.

isobject

#define isobject

(

obj

)

(obj && *((unsigned int *) obj) == OBJECTIVELY_MAGIC)

Test if the given pointer is an Object.

Definition at line 210 of file Class.h.

obj

#define obj

Value:

  , method, ...) \
  ({ \
    typeof(obj) _obj = obj; \
    _obj->interface->method(_obj, ## __VA_ARGS__); \
  })

OBJECTIVELY_MAGIC

#define OBJECTIVELY_MAGIC   0xdeadbeef

The header value identifying Objectively types.

Definition at line 205 of file Class.h.

super

#define super	(		type,
			obj,
			method,
			...
	)		interfaceof(type, _Class()->def.superclass)->method(cast(type, obj), ## __VA_ARGS__)

type

#define type

Value:

  , method, ...) \
  ({ \
    interfaceof(type, _##type())->method(__VA_ARGS__); \
  })

Function Documentation

_alloc()

OBJECTIVELY_EXPORT ident _alloc

(

Class *

clazz

)

Instantiate a type through the given Class.

Definition at line 170 of file Class.c.

                           {
 
  ident obj = calloc(1, clazz->def.instanceSize);
  assert(obj);
 
  Object *object = (Object *) obj;
 
  object->magic = OBJECTIVELY_MAGIC;
  object->clazz = clazz;
  object->referenceCount = 1;
 
  ident interface = clazz->interface;
  do {
    *(ident *) (obj + clazz->def.interfaceOffset) = interface;
  } while ((clazz = clazz->def.superclass));
 
  return obj;
}

_cast()

OBJECTIVELY_EXPORT ident _cast	(	const Class *	clazz,
		const ident	obj
	)

Perform a type-checking cast.

Definition at line 189 of file Class.c.

                                                 {
 
  if (obj) {
    const Class *c = ((Object *) obj)->clazz;
    while (c) {
 
      // as a special case, we optimize for _Object
      if (c == clazz || clazz == _Object()) {
        break;
      }
 
      c = c->def.superclass;
    }
    assert(c);
  }
 
  return (ident) obj;
}

_initialize()

OBJECTIVELY_EXPORT Class * _initialize

(

const ClassDef *

clazz

)

Initializes the given Class.

Parameters

clazz

The Class descriptor.

Returns

The initialized Class.

Definition at line 129 of file Class.c.

                                        {
 
  static Once once;
  do_once(&once, setup());
 
  assert(def);
  assert(def->name);
  assert(def->instanceSize);
  assert(def->interfaceSize);
  assert(def->interfaceOffset);
 
  Class *clazz = calloc(1, sizeof(Class));
  assert(clazz);
 
  clazz->def = *def;
 
  clazz->interface = calloc(1, def->interfaceSize);
  assert(clazz->interface);
 
  Class *superclass = clazz->def.superclass;
  if (superclass) {
 
    assert(superclass->def.instanceSize <= def->instanceSize);
    assert(superclass->def.interfaceSize <= def->interfaceSize);
 
    memcpy(clazz->interface, superclass->interface, superclass->def.interfaceSize);
  }
 
  if (clazz->def.initialize) {
    clazz->def.initialize(clazz);
  }
 
  /* def.name is a literal in the declaring image, where the ClassDef itself is
   * a compound literal with automatic storage. */
  clazz->image = imageForAddress((ident) def->name);
 
  clazz->next = __sync_lock_test_and_set(&_classes, clazz);
 
  return clazz;
}

addClassImage()

OBJECTIVELY_EXPORT void addClassImage

(

ident

handle

)

Registers an image that provides Classes, e.g. a plugin.

Parameters

handle

A handle from dlopen.

classForName resolves a name it has not yet initialized through the process-wide namespace, which holds only images loaded RTLD_GLOBAL, and which Windows does not have at all. An application that loads Classes from a plugin registers it here instead, and may then load it RTLD_LOCAL - which is how it keeps two plugins exporting the same symbols from coalescing.

Remarks

Registered images are searched most recently added first, so a newly loaded plugin answers ahead of the one it replaced.

Resolution is by Objectively's own convention, the Class name prefixed with an underscore, so nothing about the image has to be declared.

Definition at line 284 of file Class.c.

                                 {
 
  assert(handle);
  assert(_classImageCount < MAX_CLASS_IMAGES);
 
  _classImages[_classImageCount++] = handle;
}

classForName()

OBJECTIVELY_EXPORT Class * classForName

(

const char *

name

)

Returns

The Class with the given name, or NULL if no such Class has been initialized.

Remarks

Classes already initialized are answered first, then each registered image, then the process-wide namespace.

Definition at line 292 of file Class.c.

                                      {
 
  if (name) {
    Class *c = _classes;
    while (c) {
      if (strcmp(name, c->def.name) == 0) {
        return c;
      }
      c = c->next;
    }
 
    char *s;
    if (asprintf(&s, "_%s", name) > 0) {
      Class *clazz = NULL;
      Class *(*archetype)(void) = NULL;
 
      for (size_t i = _classImageCount; i > 0 && archetype == NULL; i--) {
        archetype = dlsym(_classImages[i - 1], s);
      }
 
      if (archetype == NULL) {
#if defined(_WIN32)
        static Once once;
        static ident handle;
        do_once(&once, { handle = dlopen(NULL, RTLD_LAZY); });
        archetype = handle ? dlsym(handle, s) : NULL;
#else
        archetype = dlsym(RTLD_DEFAULT, s);
#endif
      }
 
      if (archetype) {
        clazz = archetype();
      }
 
      free(s);
      return clazz;
    }
  }
 
  return NULL;
}

release()

OBJECTIVELY_EXPORT ident release

(

ident

obj

)

Atomically decrement the given Object's reference count. If the resulting reference count is 0, the Object is deallocated.

Returns

This function always returns NULL.

Definition at line 335 of file Class.c.

                         {
 
  if (obj) {
    Object *object = cast(Object, obj);
 
    assert(object);
 
    if (__sync_add_and_fetch(&object->referenceCount, -1) == 0) {
      $(object, dealloc);
    }
  }
 
  return NULL;
}

removeClassImage()

OBJECTIVELY_EXPORT void removeClassImage

(

ident

handle

)

Unregisters an image, and every Class it declared.

Parameters

handle

The handle given to addClassImage.

Remarks

Classes initialized from an image outlive it otherwise: they are cached by name, and classForName answers from that cache ahead of any image. On a platform where closing an image really unmaps it - which dlclose does on Linux and FreeLibrary does on Windows - the next lookup would then read a ClassDef that is no longer mapped. classForName compares the name of every Class it walks, so one left behind breaks every lookup, not only its own.

The Classes are not destroyed, and this is not an oversight. dlclose does not unmap on macOS, so an archetype that has already run keeps answering from its own static Class * for as long as the process lives, and would hand back whatever this freed. Unregistering is the only thing that is safe whether the image goes away or stays: the Class becomes unreachable by name, and remains valid for the archetype that owns it. The cost is the Class and its interface, which are not reclaimed.

MUST be called while the handle is still open, and only once nothing instantiated from that image survives.

Definition at line 251 of file Class.c.

                                    {
 
  assert(handle);
 
  for (size_t i = 0; i < _classImageCount; i++) {
    if (_classImages[i] == handle) {
 
      memmove(_classImages + i, _classImages + i + 1,
          (_classImageCount - i - 1) * sizeof(ident));
 
      _classImages[--_classImageCount] = NULL;
      break;
    }
  }
 
  const ident image = imageForHandle(handle);
  if (image == NULL) {
    return;
  }
 
  Class **link = &_classes;
  while (*link) {
    Class *clazz = *link;
 
    if (clazz->image == image) {
      *link = clazz->next;
      clazz->next = NULL;
    } else {
      link = &clazz->next;
    }
  }
}

retain()

OBJECTIVELY_EXPORT ident retain

(

ident

obj

)

Atomically increment the given Object's reference count.

Returns

The Object.

Remarks

By calling this, the caller is expressing ownership of the Object, and preventing it from being released. Be sure to balance calls to retain with calls to release.

Definition at line 350 of file Class.c.

                        {
 
  Object *object = cast(Object, obj);
 
  assert(object);
 
  __sync_add_and_fetch(&object->referenceCount, 1);
 
  return obj;
}

Variable Documentation

_pageSize

OBJECTIVELY_EXPORT size_t _pageSize

The page size, in bytes, of the target host.

Definition at line 200 of file Class.h.