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, const ident address)
	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 226 of file Class.h.

   { \
    typeof(obj) _obj = (obj); \
    ((typeof(_obj->interface[0])) classof(_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 232 of file Class.h.

classnameof

#define classnameof

(

obj

)

classof(obj)->def.name

Resolve the Class name of the given Object instance.

Definition at line 244 of file Class.h.

classof

#define classof

(

obj

)

((Object *) obj)->clazz

Resolve the Class of an Object instance.

Definition at line 238 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 220 of file Class.h.

interfaceof

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

Resolve the typed interface of a Class.

Definition at line 250 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 214 of file Class.h.

obj

#define obj

Value:

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

OBJECTIVELY_MAGIC

#define OBJECTIVELY_MAGIC   0xdeadbeef

The header value identifying Objectively types.

Definition at line 209 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 198 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;
 
  return obj;
}

_cast()

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

Perform a type-checking cast.

Definition at line 212 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 151 of file Class.c.

                                        {
 
  static Once once;
  do_once(&once, setup());
 
  assert(def);
  assert(def->name);
  assert(def->instanceSize);
  assert(def->interfaceSize);
 
  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);
 
  /* Taken here rather than around the whole function: def.initialize above can
   * reach other archetypes, and so this, before that Class is published. */
  pthread_mutex_lock(&_classesLock);
 
  clazz->next = _classes;
  _classes = clazz;
 
  pthread_mutex_unlock(&_classesLock);
 
  return clazz;
}

addClassImage()

OBJECTIVELY_EXPORT void addClassImage	(	ident	handle,
		const ident	address
	)

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

Parameters

handle	A handle from dlopen.
address	Any address within that image, such as the entry point the application resolved from handle.

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.

address is what identifies the image. Classes record the base address of the image that declared them, and the platforms report that for an address, not for a handle, so this takes one that the caller can vouch for. Aborts if no loaded image contains it.

Definition at line 231 of file Class.c.

                                                      {
 
  assert(handle);
  assert(address);
 
  const ident image = imageForAddress(address);
  if (image == NULL) {
    fprintf(stderr, "%s: no image contains %p\n", __func__, address);
    abort();
  }
 
  ClassImage *classImage = calloc(1, sizeof(ClassImage));
  assert(classImage);
 
  classImage->handle = handle;
  classImage->image = image;
 
  /* Published the same way a Class is, and for the same reason: classForName
   * walks this list on any thread. */
  classImage->next = __atomic_load_n(&_images, __ATOMIC_RELAXED);
  while (!__atomic_compare_exchange_n(&_images, &classImage->next, classImage, 1,
      __ATOMIC_RELEASE, __ATOMIC_RELAXED)) ;
}

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 300 of file Class.c.

                                      {
 
  if (name) {
    pthread_mutex_lock(&_classesLock);
 
    Class *c = _classes;
    while (c) {
      if (strcmp(name, c->def.name) == 0) {
        break;
      }
      c = c->next;
    }
 
    pthread_mutex_unlock(&_classesLock);
 
    if (c) {
      return c;
    }
 
    char *s;
    if (asprintf(&s, "_%s", name) > 0) {
      Class *clazz = NULL;
      Class *(*archetype)(void) = NULL;
 
      for (ClassImage *i = __atomic_load_n(&_images, __ATOMIC_ACQUIRE);
          i && archetype == NULL; i = i->next) {
 
        ident handle = __atomic_load_n(&i->handle, __ATOMIC_ACQUIRE);
        if (handle) {
          archetype = dlsym(handle, 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 356 of file Class.c.

                         {
 
  if (obj) {
    Object *object = cast(Object, obj);
 
    assert(object);
 
    if (__atomic_fetch_sub(&object->referenceCount, 1, __ATOMIC_RELEASE) == 1) {
      __atomic_thread_fence(__ATOMIC_ACQUIRE);
      $(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.

Aborts if handle was not registered, rather than leaving the Classes it declared behind, which is the failure this exists to prevent. Two calls for the same handle abort on the second, whichever order they arrive in.

Definition at line 255 of file Class.c.

                                    {
 
  assert(handle);
 
  /* Held from the search to the last unlink, so that retiring an image and
   * dropping its Classes is one operation, and a second call for the same handle
   * finds it already gone. Nothing here reaches the loader. */
  pthread_mutex_lock(&_classesLock);
 
  ident image = NULL;
 
  /* Retired in place rather than unlinked, so that a concurrent classForName
   * parked on this node still has a next to follow, and never reads a node that
   * has been freed. Retiring is a single store of the handle it matches on, so
   * that walk sees this image or does not, and never half of it. Retired nodes
   * are freed at teardown; reusing one would put a newly registered image where
   * the retired one sat, and lookup order is newest first. */
  for (ClassImage *i = __atomic_load_n(&_images, __ATOMIC_ACQUIRE); i; i = i->next) {
    if (__atomic_load_n(&i->handle, __ATOMIC_ACQUIRE) == handle) {
      image = i->image;
      __atomic_store_n(&i->handle, NULL, __ATOMIC_RELEASE);
      break;
    }
  }
 
  if (image == NULL) {
    fprintf(stderr, "%s: %p was never registered\n", __func__, handle);
    abort();
  }
 
  Class **classes = &_classes;
  while (*classes) {
    Class *clazz = *classes;
 
    if (clazz->image == image) {
      *classes = clazz->next;
      clazz->next = NULL;
    } else {
      classes = &clazz->next;
    }
  }
 
  pthread_mutex_unlock(&_classesLock);
}

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 372 of file Class.c.

                        {
 
  Object *object = cast(Object, obj);
 
  assert(object);
 
  /* A reference count of zero means another thread is already inside dealloc,
   * and the caller is retaining memory that is about to be freed. */
  unsigned int referenceCount = __atomic_load_n(&object->referenceCount, __ATOMIC_RELAXED);
  do {
    if (referenceCount == 0) {
      fprintf(stderr, "%s: %p is being deallocated\n", __func__, object);
      abort();
    }
  } while (!__atomic_compare_exchange_n(&object->referenceCount, &referenceCount,
      referenceCount + 1, 1, __ATOMIC_RELAXED, __ATOMIC_RELAXED));
 
  return obj;
}

Variable Documentation

_pageSize

OBJECTIVELY_EXPORT size_t _pageSize

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

Definition at line 204 of file Class.h.