Class.c File Reference

#include "Config.h"
#include <assert.h>
#include <dlfcn.h>
#include <pthread.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "Class.h"
#include "Object.h"

Go to the source code of this file.

Data Structures
struct	ClassImage
	A registered image: the handle the application holds, and the base address that the Classes it declares record in Class::image. More...

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

Variables
static Class *	_classes
static pthread_mutex_t	_classesLock = PTHREAD_MUTEX_INITIALIZER
	Guards the structure of _classes. MUST NOT be held across dlsym, dlopen, or a Class initializer, each of which can reenter _initialize.
static ClassImage *	_images
	The registered images providing Classes, most recently added first. Published atomically rather than under _classesLock, which cannot be held across the dlsym this list exists for. A plain list rather than a MutableArray, because Class is beneath the collections.
size_t	_pageSize

Function Documentation

_alloc()

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()

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()

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()

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()

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;
}

imageForAddress()

static const ident imageForAddress ( const ident  address )

static

Returns

The base address of the image containing address, or NULL.

Remarks

The Windows dlfcn shim has no dladdr. UNCHANGED_REFCOUNT matters: without it this would pin the very module the caller is about to release.

Definition at line 131 of file Class.c.

                                                        {
 
  assert(address);
 
#if defined(_WIN32)
  HMODULE module;
  if (GetModuleHandleExA(GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS |
      GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, (LPCSTR) address, &module)) {
    return module;
  }
#else
  Dl_info info;
  if (dladdr(address, &info)) {
    return info.dli_fbase;
  }
#endif
 
  return NULL;
}

release()

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()

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()

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;
}

setup()

static void setup ( void  )

static

Called when initializing Object to setup Objectively.

Definition at line 113 of file Class.c.

                        {
 
  _classes = NULL;
 
#if !defined(_SC_PAGESIZE)
  _pageSize = 4096;
#else
  _pageSize = sysconf(_SC_PAGESIZE);
#endif
 
  atexit(teardown);
}

teardown()

static void teardown ( void  )

static

Called atexit to teardown Objectively.

Definition at line 76 of file Class.c.

                           {
  Class *c;
 
  c = _classes;
  while (c) {
    if (c->def.destroy) {
      c->def.destroy(c);
    }
 
    c = c->next;
  }
 
  c = _classes;
  while (c) {
 
    Class *next = c->next;
 
    free(c->interface);
    free(c);
 
    c = next;
  }
 
  ClassImage *i = _images;
  while (i) {
 
    ClassImage *next = i->next;
 
    free(i);
 
    i = next;
  }
}

Variable Documentation

_classes

Class* _classes

static

Definition at line 46 of file Class.c.

_classesLock

pthread_mutex_t _classesLock = PTHREAD_MUTEX_INITIALIZER

static

Guards the structure of _classes. MUST NOT be held across dlsym, dlopen, or a Class initializer, each of which can reenter _initialize.

Definition at line 52 of file Class.c.

_images

ClassImage* _images

static

The registered images providing Classes, most recently added first. Published atomically rather than under _classesLock, which cannot be held across the dlsym this list exists for. A plain list rather than a MutableArray, because Class is beneath the collections.

Definition at line 71 of file Class.c.

_pageSize

size_t _pageSize

Definition at line 44 of file Class.c.