A.1 Well known functions for struct types

The macros for “well known functions” define an API for the basic operations upon a data struct. The following macros are defined in the header file ccnames.h.

Macro: ccname_init (STRUCT_TYPE)

Macro: ccname_init (STRUCT_TYPE, VARIANT)

Macro: ccname_init (STRUCT_TYPE, VARIANT1, VARIANT2)

Macro: ccname_init (STRUCT_TYPE, VARIANT1, VARIANT3)

Given a struct type name and an optional variant specification: expand into the name of the API function init().

Functions with this name are constructors for struct instances allocated on the stack or embedded into enclosing struct instances. They allocate all the asynchronous resources and initialise the struct fields.

Macro: ccname_final (STRUCT_TYPE)

Given a struct type name: expand into the name of the API function final().

Functions with this name are destructors for struct instances allocated on the stack or embedded into enclosing struct instances. They release all the asynchronous resources associated to the struct fields.

Macro: ccname_alloc (STRUCT_TYPE)

Macro: ccname_alloc (STRUCT_TYPE, VARIANT)

Given a struct type name and an optional variant specification: expand into the name of the API function alloc().

Functions of this type are memory allocators for struct instances allocated on the heap. They might perform the allocation using the API of the library CCMemory.

Macro: ccname_release (STRUCT_TYPE)

Given a struct type name: expand into the name of the API function release().

Functions of this type are memory releasers for struct instances allocated on the heap. They might perform the release using the API of the library CCMemory.

Macro: ccname_new (STRUCT_TYPE)

Macro: ccname_new (STRUCT_TYPE, VARIANT)

Macro: ccname_new (STRUCT_TYPE, VARIANT1, VARIANT2)

Macro: ccname_new (STRUCT_TYPE, VARIANT1, VARIANT3)

Given a struct type name and an optional variant specification: expand into the name of the API function new().

Functions with this name are constructors for struct instances allocated on the heap. The memory allocation is performed by calling the alloc() function. The initialisation of the fields is performed by calling the init() function.

Macro: ccname_delete (STRUCT_TYPE)

Given a struct type name: expand into the name of the API function delete().

Functions with this name are destructors for struct instances allocated on the heap. The finalisation of the fields is performed by calling the final() function. The memory release is performed by calling the release() function.

An example of common function implementation for struct types:

#include <ccexceptions.h>
#include <ccmemory.h>
#include <ccnames.h>
#include <stdio.h>
#include <stdlib.h>
#include <math.h>

typedef struct my_coords_t      my_coords_t;

struct my_coords_t {
  double        X;
  double        Y;
};

void
ccname_init(my_coords_t, rec) (my_coords_t * S, double X, double Y)
{
  S->X = X;
  S->Y = Y;
}

void
ccname_init(my_coords_t, pol) (my_coords_t * S, double RHO, double THETA)
{
  S->X = RHO * cos(THETA);
  S->Y = RHO * sin(THETA);
}

void
ccname_final(my_coords_t) (my_coords_t * S)
{
}

static my_coords_t *
ccname_alloc(my_coords_t) (cce_destination_t L)
{
  return (my_coords_t *)ccmem_std_malloc(L, sizeof(my_coords_t));
}

static void
ccname_release(my_coords_t) (my_coords_t * S)
{
  ccmem_std_free(S);
}

my_coords_t *
ccname_new(my_coords_t, rec) (cce_destination_t L, double X, double Y)
{
  my_coords_t * S = ccname_alloc(my_coords_t)(L);

  ccname_init(my_coords_t, rec)(S, X, Y);
  return S;
}

my_coords_t *
ccname_new(my_coords_t, pol) (cce_destination_t L, double RHO, double THETA)
{
  my_coords_t * S = ccname_alloc(my_coords_t)(L);

  ccname_init(my_coords_t, pol)(S, RHO, THETA);
  return S;
}

void
ccname_delete(my_coords_t) (my_coords_t * S)
{
  ccname_final(my_coords_t)(S);
  ccname_release(my_coords_t)(S);
}

int
main (void)
{
  cce_location_t        L[1];
  my_coords_t *         S;

  if (cce_location(L)) {
    cce_run_catch_handlers_final(L);
  } else {
    S = ccname_new(my_coords_t, rec)(L, 1.0, 2.0);

    printf("X=%f, Y=%f\n", S->X, S->Y);
    ccname_delete(my_coords_t)(S);
  }
  exit(EXIT_SUCCESS);
}

This document describes version 0.3.0-devel.3 of CCStructs.