Cyclone User's Manual

1  Introduction

1.1  Acknowledgements

2  Cyclone for C Programmers

2.1  Getting Started

    #include <stdio.h>

    int main() {
      printf("hello, world\n");
      return 0;
    }

    cyclone -o hello hello.cyc 

    hello

    hello, world

    #include <stdio.h>

    int main() {
      printf("hello, world\n");
    }

2.2  Pointers

Nullable Pointers

    int x = 3;
    int *y = &x;

    *y = *y + 1;

• You can't cast an integer to a pointer. Cyclone prevents this because it would let you overwrite arbitrary memory locations. In Cyclone, NULL is a keyword suitable for situations where you would use a (casted) 0 in C. The compiler accepts 0 as a legal possibly-null pointer value, but using NULL is preferred.
• You can't do pointer arithmetic on a * pointer. Pointer arithmetic in C can take a pointer out of bounds, so that when the pointer is eventually dereferenced, it corrupts memory or causes a crash. (However, pointer arithmetic is possible using @fat and @zeroterm pointers.)
• There is one other way to crash a C program using pointers: you can dereference the NULL pointer or try to update the NULL location. Cyclone prevents this by inserting a null check whenever you dereference a * pointer (that is, whenever you use the *, ->, or subscript operation on a pointer.)

Fat Pointers

    #include <stdio.h>

    int main(int argc, char *@fat *@fat argv) {
      argc--; argv++; /* skip command name */
      if (argc > 0) {
        /* print first arg without a preceding space */
        printf("%s",*argv);
        argc--; argv++;
      }
      while (argc > 0) {
        /* print other args with a preceding space */
        printf(" %s",*argv);
        argc--; argv++;
      }
      printf("\n");
      return 0;
    }

  int main(int argc, char ?? argv);

  int main(int argc, char *@fat *@fat argv);

Non-NULL Pointers

    int getc(FILE *@notnull);

    FILE *f = fopen("/etc/passwd","r");
    int c = getc((FILE *@notnull)f);

    FILE *f = fopen("/etc/passwd","r");
    if (f == NULL) {
      fprintf(stderr,"cannot open passwd file!");
      exit(-1);
    }
    int c = getc(f);

Zero-Terminated Pointers

  void foo(char *s, int offset) {
     unsigned int len = strlen(s);
     for (unsigned int i = 0; offset+i < len; i++)
        s[offset+i] = 'a';
  }

  void foo(char *s, int offset) {
     unsigned int len = strlen(s);
     s += offset;
     for (unsigned int i = 0; offset+i < len; i++, s++)
        *s = 'a';
  }

  void foo(char *s, int offset) {
    char *@fat @nozeroterm fat_s = (char *@fat @nozeroterm)s;
    unsigned int len; 
    fat_s += offset;
    len = numelts(fat_s);    
    for (unsigned int i = 0; i < len; i++)
      fat_s[i] = 'a';
  }

struct _tagged_arr { 
  char *base;
  char *curr;
  char *last;
};

void Cyc_foo(char *s,int offset){
  struct _tagged_arr fat_s = {s, s, s+strlen(s)};
  unsigned int len;
  fat_s.curr += offset;
  if (fat_s.curr < fat_s.base || fat_s.curr >= fat_s.last) 
    len = 0;
  else 
    len = fat_s.last - fat_s.curr;
  { unsigned int i = 0;
    for(0; i < len; i++)
      fat_s.curr[i] = 'a';
  }
}

Initializing Pointers

Other features of pointers

void foo(int *@numelts(4) arr);

2.3  Regions

struct Point {int x; int y;};

struct Point *newPoint(int x,int y) {
  struct Point result = {x,y};
  return &result;
}

void foo(struct Point *p) {
  p->y = 1234;
  return;
}

void bar() {
  struct Point *p = newPoint(1,2);
  foo(p);
}

1 int f() {
2    int x = 0;
3    int *@region(`f) y = &x;
4    L:{ int a = 0;
5        y = &a;
6      }
7    return *y;
8 }

Region Inference

1 int f() {
2    int x = 0;
3    int *y = &x;
4    { int a = 0;
5      y = &a;
6    }
7    return *y;
8 }

The Heap Region

struct Point p = {0,1};
struct Point *ptr = &p;

struct Point p = {0,1};
struct Point *@region(`H) ptr = &p;

struct Point *@region(`H) good_newPoint(int x,int y) {
  struct Point *@region(`H) p = 
    malloc(sizeof(struct Point));
  p->x = x;
  p->y = y;
  return p;
}

struct Point *@region(`H) good_newPoint(int x,int y) {
  return new Point{x,y};
}

Growable Regions

{ region<`r> h;
   ...
}

int k(int n) {
  int result;
  { region<`r> h;
    int ?arr = rnew(h) {for i < n : i};
    result = process(h, arr);
  }
  return result;
}

Dynamic Regions

  let NewRegion{<`d> dh} = Core::rnew_dynregion(rh);

  { region sh = open(dh);
    ...
  }

  Core::free_dynregion(dh);

Region Polymorphism

void foo(struct Point *@region(`r) p) {
  p->y = 1234;
  return;
}

void g() {
  struct Point p = {0,1};
  struct Point *@region(`g) ptr1 = &p;
  struct Point *@region(`H) ptr2 = new Point{2,3};
  foo(ptr1);
  foo(ptr2);
}

void foo(struct Point * p) {
  p->y = 1234;
  return;
}

void h(struct Point * p1, struct Point * p2) {
  p1->x += p2->x;
  p2->x += p2->y;
}

void h(struct Point *@region(`r1) p1, 
       struct Point *@region(`r2) p2) {
  p1->x += p2->x;
  p2->x += p2->y;
}

void j(struct Point * p1, struct Point * p2) {
  p1 = p2;
}

void j(struct Point *@region(`r1) p1, 
       struct Point *@region(`r2) p2) {
  p1 = p2;
}

void j(struct Point *@region(`r) p1, 
       struct Point *@region(`r) p2) {
  p1 = p2;
}

struct Point * good_newPoint(int x,int y) {
  return new Point{x,y};
}

struct Point *newPoint(int x,int y) {
  struct Point result = {x,y};
  return &result;
}

int * id(int *x) {
  return x;
}

int *@region(`H) id(int *@region(`r) x) {
  return x;
}

int *@region(`r) id(int *@region(`r) x) {
  return x;
}

int *`r id(int *`r x) {
  return x;
}

Region Summary

2.4  Tagged Unions and Datatypes

    printf("%d",x);

    printf("%s",x);

    printf(s,x);

    @tagged union T {
      int Integer;
      const char *@fat String;
    };
    union T x = {.Integer = 3};
    union T y = {.String = "hello, world"};

    bool printT(union T w) {
      if (tagcheck(w.Integer))
        printf("%d",w);
      else 
        printf("%s",w);
    }

    union T a;
    int x;
    a.String = "hello, world";
    /* Next line fails */
    x = a.Integer + 3;

    void printT(union T a) {
      switch (a) {
      case {.Integer = i}: printf("%d",i); return;
      case {.String = s}: printf("%s",s); return;
      }
    }

   case {.Integer = i}: printf("%d",i); return;

    datatype T {
      Integer(int);
      String(const char *@fat);
    };

    datatype T.Integer x = Integer(3);
    datatype T.String y = String("hello, world");

    void printT(datatype T@ a) {
      switch (a) {
      case &Integer(i): printf("%d",i); return;
      case &String(s): printf("%s",s); return;
      }
    }

2.5  Exceptions

    FILE *f = fopen("/etc/passwd","r");
    int c = getc((FILE @)f);

    Uncaught exception Null_Exception

    FILE *f = fopen("/etc/passwd","r");
    int c;
    try {
      c = getc((FILE *@notnull)f);
    }
    catch {
    case &Null_Exception:
      printf("Error: can't open /etc/passwd\n");
      exit(1);
    case &InvalidArg(s):
      printf("Error: InvalidArg(%s)\n",s);
      exit(1);
    }

    @extensible datatype exn {
      My_Exception(char *@fat);
    };

    throw new My_Exception("some kind of error");

    throw new Null_Exception;

    datatype exn {
      My_Exception(char ?);
    };

2.6  Additional Features of Cyclone

2.7  GCC and C99 Additions

• Statement expressions: There is a new expression form, ({ statement expression }). The statement is executed first, then the expression, and the value of the entire expression is the value of the expression
• Struct and Union expressions: If you've declared struct point{int x; int y;}; then you can write point{.x=expression, .y=expression} to allocate and initialize a struct point. The same sort of constructors may be used for unions, tagged or not.
• // comments as in Java or C++
• Declarations can appear in any statement position. It is not necessary to wrap braces around the declaration of a local variable.
• For-statements can include a declaration. For instance:

    for (int x=0; x < n; x++) { 
      ...
    }
  

2.8  Tuples

  $(int,char,bool) x = $(42,'z',true)

  if (x[2])
    x[0]++;

  struct {int f0; char f1; bool f2;} x = {42,'z',true};
  if (x.f2)
    x.f1++;

2.9  Creating Arrays

  int foo[8] = {1,2,3,4,5,6,7,8};
  char s[4] = "bar";

  // foo is a pointer to a heap-allocated array
  int *{8}foo = new {1,2,3,4,5,6,7,8};

  // s is a checked pointer to a heap-allocated string
  char ?s = new "bar";

  // a non-null pointer to the first 100 even numbers
  int @{100}evens = new {for i < 100 : 2*i};

2.10  Subtyping

  typedef struct Point {float x,y;} *point;

  typedef struct CPoint {float x,y; int color;} *cpoint;

  float xcoord(point p) {
    return p->x;
  }

2.11  Let Declarations

  int foo(int x) {
    let y = x+3;
    let z = 3.14159;
    return (int)(y*z);
  }

  int sum($(int,int,int) args) {
    let $(x,y,z) = args;
    return (x+y+z);
  }

2.12  Polymorphic Functions

  $(char*,int) swap1($(int,char*) x) {
     return $(x[1], x[0]);
  }
  $(int,int) swap2($(int,int) x) {
     return $(x[1], x[0]);
  }

  $(void *,void *) swap1($(void *,void *) x) {
     return $(x[1], x[0]);
  }

  $(`b,`a) swap($(`a,`b) x) {
     return $(x[1],x[0]);
  }

  let $(x,y) = swap($("hello",3));  // x is 3, y is hello
  let $(w,z) = swap($(4,3));        // w is 3, z is 4

2.13  Polymorphic Data Structures

  struct List<`a> {`a hd; struct List<`a> * tl; };
  typedef struct List<`a> *list_t<`a>;

  list_t<int> ilist = new List{1,new List{2,null}};
  list_t<string_t> slist = new List{.hd = "foo",
                                  .tl = new List{"bar",null}};

2.14  Abstract and Existential Types

  abstract struct Queue<`a> { list_t<`a> front, rear; };

  extern struct Queue<`a>;

typedef _ foo_t;

typedef _::A bar_t;

2.15  Restrictions

• Cyclone does not permit some of the casts that are allowed in C because incorrect casts can lead to crashes, and it is not always possible for us to determine what is safe. In general, you should be able to cast something from one type to another as long as the underlying representations are compatible. Note that Cyclone is very conservative about ``compatible'' because it does not know the size or alignment constraints of your C compiler.
  
  
• Cyclone does not support pointer arithmetic on thin pointers unless they are zero-terminated and even then, there are checks to make sure you can't go past a zero. Pointer arithmetic is not unsafe in itself, but it can lead to unsafe code when the resulting pointer is assigned or dereferenced. You can cast the thin pointer value to a @fat value and then do the pointer arithmetic instead.
  
  
• Cyclone inserts a NULL check when a possibly-NULL pointer is dereferenced and it cannot determine statically that the pointer is not NULL.
  
  
• If a function's return type is not ``bits-only'' (i.e., contains pointers), Cyclone requires that the function executes a return statement, throws an exception, or calls a noreturn function on every possible execution path. This is needed to ensure that the value returned from the function has the right type, and is not just a random value left in a register or on the stack.
  
  
• Untagged unions in Cyclone can hold arbitrary values, but you can only read out ``bits.'' In particular, the members you can read out can only have combinations of chars, ints, shorts, longs, floats, doubles, structs of bits, or tuples of bits. Pointer types are not supported. This avoids the situation where an arbitrary bit pattern is cast to a pointer and then dereferenced. If you want to use multiple types, then use @tagged unions or datatypes.
  
  
• Cyclone only supports limited forms of malloc (and calloc). You must write malloc(sizeof(t)*n) and t must be a ``bits-only'' type. You can use calloc to allocate arrays of (possibly NULL) pointers (e.g., calloc(sizeof(char*),34)).
  
  
• Cyclone performs a static analysis to ensure that every non-numeric (i.e., pointer) variable and struct field is initialized before it is used. This prevents a random stack value from being used improperly. The analysis is somewhat conservative so you may need to initialize things earlier than you would do in C. There is only limited support for initializing memory in a procedure separate from the one that does the allocation.
  
  
• Cyclone does not permit gotos from one scope into another. C warns against this practice, as it can cause crashes; Cyclone rules it out entirely.
  
  
• Cyclone places some limitations on the form of switch statements that rule out crashes like those caused by unrestricted goto. Furthermore, Cyclone prevents you from accidentally falling through from one case to another. To fall through, you must explicitly use the fallthru keyword. Otherwise, you must explicitly break, goto, continue, return, or throw an exception. However, adjacent cases for a switch statement (with no intervening statement) do not require an explicit fallthru.
  
  
• In the near future, Cyclone will place some restrictions on linking for safety reasons. In particular, if you import a variable or function with one type, then it must be exported by another file with that type. In addition, access to C code will be restricted based on a notion of security roles.
  
  
• Cyclone has some new keywords (beyond those of C99 and GCC) that can no longer be used as identifiers. The list includes: abstract, alias, calloc, datatype, dynregion_t, export, fallthru, __gen, let, malloc, namespace, numelts, __cyclone_port_on__, __cyclone_port_off__, region, regions, reset_region, rmalloc, rnew, tagcheck, tag_t, throw, try, using, valueof, and valueof_t.
  
  
• Cyclone prevents you from using pointers to stack-allocated objects as freely as in C to avoid security holes. The reason is that each declaration block is placed in a conceptual ``region'' and the type system tracks the region into which a pointer points.
  
  
• Cyclone does not allow you to explicitly free a heap-allocated object. Instead, you can either use the region mechanism or rely upon the conservative garbage collector to reclaim the space.

• Cyclone currently does not support nested type declarations within a function. All struct, union, enum, datatype, and typedef definitions must be at the top-level.
  
  
• Cyclone does not allow a typedef declaration to be shadowed by another declaration.

3  Pointers

• @nullable: Pointers with this qualifier may be NULL. This qualifier is present by default and overridden by the @notnull qualifier. A dereference of a @nullable pointer will generally be preceded by a NULL-check.
  
  
• @notnull: Pointers with this qualifier may never be NULL, and thus never need to be checked for NULL upon dereference. This qualifier is not present by default and must be put in explicitly. The qualifier may be abbreviated by using ``@'' in place of the usual pointer ``*''. So, for instance, the type ``int *@notnull'' can be abbreviated by ``int @''. Currently, the @notnull qualifier cannot be used on pointers with the @fat qualifier.
  
  
• @thin: Pointers with this qualifier have the same representation as in C (i.e., a single machine word.) However, arithmetic on thin pointers is not supported except when the pointer is also qualified as @zeroterm (see below). This qualifier is present by default and overridden by the @fat qualifier.
  
  
• @fat: Pointers with this qualifier consist of a thin pointer plus additional information needed to support safe pointer arithmetic and dereferencing. (The current implementation uses three words in total.) Each dereference of a fat pointer incurs both a NULL-check and a bounds check to ensure that the pointer points to a valid object. The @fat qualifier cannot be used with the @notnull or @numelts qualifiers (though we expect to change this in the future.) The numelts operation may be applied to fat pointers to determine the number of elements in the (forward) sequence that may be safely dereferenced. Finally, the qualifier may be abbreviated by using ``?'' in place of the usual pointer ``*''. So, for instance, the type ``int *@fat'' can be abbreviated by ``int ?''.
  
  
• @numelts(e): The term e must be a static expression (i.e., a constant expression or one involving valueof) and indicates an upper bound on the number of objects that that the pointer refers to. For example, if p has type T *@numelts(42), then either p is NULL or else for 0 £ i < e, the expression p[i] is guaranteed to contain a T object. This qualifier may not be used in conjunction with @fat. If omitted on a @thin pointer, then @numelts(1) is inserted by default. This qualifier can be abbreviated by writing the bounds expression e in curly braces. For instance, the type ``int *@numelts(42)'' can be abbreviated by ``int *{42}''.
  
  
• @zeroterm: This qualifier is used for zero-terminated sequences, such as C-style strings, and provides an alternative to fat pointers for doing safe pointer arithmetic without knowing bounds statically. This qualifier can only be used on pointers whose element type admits zero or NULL as a value, including integral types, and @nullable pointer types. Arithmetic in the forward direction is possible with zero-terminated pointers (e.g., p++) as is a subscript with a positive index (e.g., p[i]). However, the compiler inserts code to ensure that the index does not step over the final zero. When updating a zero-terminated array, the compiler also ensures that the final zero is not overwritten with a non-zero value. It is generally best to coerce a thin, zero-terminated pointer to a fat, zero-terminated pointer to avoid these overheads. This qualifier is only present by default for char pointers. It can be overridden with the @nozeroterm qualifier. This qualifier may also be used on array types.
  
  
• @nozeroterm: This qualifier is present by default on all pointer types except for char pointers. It is used to override the implicit @zeroterm qualfier for char pointers. This qualifier may also be used on array types.
  
  
• @region(`r): This qualifier is used to indicate the region into which a pointer points (in this case region `r). The qualifier may be abbreviated by simply writing the region name after any other Cyclone qualifiers. For instance, the type ``int *@notnull @region`r'' may be abbreviated as ``int @`r''. The rules about default region annotations are context-dependent and therefore described below.

3.1  Pointer Subtyping

  void foo(int x) {
    int *@region(`foo) y = &x;
    L:{
      int *@region(`L) z = y;
    }
  }

  void bar(int *@region(`r) x,
           int *@region(`s) y : {`s} > `r);

// nullable int pointers
typedef int * nintptr_t;
// not-nullable int pointers
typedef int *@notnull intptr_t;

  void f(int *@notnull *@notnull x) {
    int *@nullable *@notnull y = x; 
    // would be legal if int *@nullable *@notnull 
    // was a subtype of int *@notnull *@notnull.
    *y = NULL;    
    // legal because *y has type int *@nullable
    **x;          
    // seg faults even though the type of *x is 
    // int *@notnull
  }

3.2  Pointer Coercions

  int arr[42];
  int *@thin @numelts(42) p = arr;
  int *@fat pfat = p;

  int strlen(char *@zeroterm s) {
    char *@fat @zeroterm sfat = s;
    return numelts(s);
  }

• T can be coerced to S when T is a subtype of S.
• T*@nullable can be coerced to T*@notnull but might throw an exception at run-time.
• T*@thin@numelts(c) can be coerced to T*@fat when c is a constant expression.
• T*@fat can be coerced to T*@thin @numelts(c) when c is a constant expression, but might throw an exception at run-time.
• T*@thin@zeroterm can be coerced to T*@fat@zeroterm and vice versa.
• T*@thin@zeroterm can be coerced to const T*@fat@nozeroterm.
• T*@thin@zeroterm can be coerced to T*@fat@nozeroterm, but access to the trailing zero is lost.

3.3  Default Region Qualifiers

• In function-argument types, a fresh (polymorphic) region name is used.
• In function-return types, `H is used.
• In type definitions, including typedef, `H is used.
• In function bodies, unification is used to infer the region based on how the location assigned the pointer type is used in the function.

typedef int * foo_t;
void g(foo_t);

void g(int *);

typedef int *@region(`H) foo_t;
void g(foo_t);

void g(int *@region(`r));

3.4  Static Expression Bounds

  int sum(tag_t<`n> num, 
          int *@notnull @numelts(valueof(`n)) p) {
    int a = 0;
    for (unsigned i = 0; i < num; i++) 
      a += p[i];
  }

  int sum(tag_t num, int p[num]);

4  Tagged Unions and Datatypes

4.1  Tagged Unions

   @tagged union Foo {
      int i;
      double d;
      char *@fat s;
   };

  union Foo x;
  x.i = 3;
  x.s = "hello";

  void printFoo(union Foo x) {
    if (tagcheck(x.i))
      printf("%d",x.i);
    else if (tagcheck(x.d))
      printf("%g",x.d);
    else if (tagcheck(x.s))
      printf("%s",x.s);
  }

  void printFoo(union Foo x) {
    switch (x) {
    case {.i = i}: printf("%d",i); break;
    case {.d = d}: printf("%g",d); break;
    case {.s = s}: printf("%s",s); break;
    }
  }

4.2  Datatypes

  datatype Color { Red, Green, Blue };

  datatype Color.Red red = Red;
  datatype Color *c = &red;

  datatype Shape {
    Point,
    Circle(float),
    Ellipse(float,float),
    Polygon(int,float),
  };

  datatype Shape *s1 = new Point;
  datatype Shape *s2 = new Circle(3.0);

  enum Unops { Negate, Invert};
  enum Binops { Add, Subtract, Multiply, Divide };
  typedef datatype Exp *@notnull exp_t;
  datatype Exp {
    Int(int),
    Float(float),
    Unop(enum Unops, exp_t),
    Binop(enum Binops, exp_t, exp_t)
  };

  exp_t double_exp(datatype Exp e) {
    return new Binop(Multiply, e, new Int(2));
  }

Accessing Datatype Variants

  bool isCircle(datatype Shape *s) {
    switch(s) {
    case &Circle(r): return true;
    default: return false;
    }
  }

  extern area_of_ellipse(float,float);
  extern area_of_poly(int,float);
  float area(datatype Shape *s) {
    float ans;
    switch(s) {
    case &Point:
      ans = 0;
      break;
    case &Circle(r):
      ans = 3.14*r*r;
      break;
    case &Ellipse(r1,r2):
      ans = area_of_ellipse(r1,r2);
      break;
    case &Polygon(sides,r):
      ans = area_of_poly(sides,r);
      break;
    }
    return ans;
  }

• It is possible that a member of the datatype type matches none of the cases. Note that default matches everything.
• A case is useless because it could only match if one of the earlier cases match. For example, a default case at the end of the switch in area would be an error.

Polymorphism and Datatypes

  datatype Tree<`a>  {
    Leaf(`a);
    Node(datatype Tree<`a>*, datatype Tree<`a>*);
  };

  datatype Tree<`a,`r>  {
    Leaf(`a);
    Node(datatype Tree<`a,`r> *`r, 
         datatype Tree<`a,`r> *`r);
  };

Future

• Currently, given a value of a variant type (e.g., datatype Shape.Circle), the only way to access the fields is with pattern-matching even though the variant is known. We may provide a tuple-like syntax in the future.

4.3  Extensible Datatypes

  @extensible datatype Food;
  datatype Food { Banana; Grape; 
                  Pizza(list_t<datatype Food*>) };
  datatype Food { Candy; Broccoli };

  datatype exn {BadFilename(string)};

5  Pattern Matching

5.1  Let Declarations

  let x = e;

  struct Pair {  int x; int y; };
  void f(struct Pair pr) {
    let Pair(fst,snd) = pr;
    ...
  }

  struct Quad { struct Pair p1; struct Pair p2; };

• Quad(Pair(a,b),Pair(c,d))
• Quad(p1, Pair(c,d))
• Quad(Pair(a,b), p2)
• Quad(p1,p2)
• q

5.2  Pattern Forms

• The syntax
• The types of expressions it can match against (to avoid a compile-time error)
• The expressions the pattern matches against (other expressions cause a match failure)
• The bindings the pattern introduces, if any.

• Variable patterns
  • Syntax: an identifer
  • Types for match: all types
  • Expressions matched: all expressions
  • Bindings introduced: the identifier is bound to the expression being matched
• Wildcard patterns
  • Syntax: _ (underscore, note this use is completely independent of _ for type inference)
  • Type for match: all types
  • Expressions matched: all expressions
  • Bindings introduced: none. Hence it is like a variable pattern that uses a fresh identifier. Using _ is better style because it indicates the value matched is not used. Notice that ``let _ = e;'' is equivalent to e.
  
  
  
• As patterns
  • Syntax: x as p where x is an identifier and p is a pattern.
  • Types for match: all types
  • Expressions matched: all expressions
  • Bindings introduced: if the expression matches the pattern p, then its value is bound to x. Thus, a variable pattern is simply shorthand for ``x as _''.
  
  
  
• Reference patterns
  • Syntax: *x (i.e., the * character followed by an identifier)
  • Types for match: all types
  • Expressions matched: all expressions. (Very subtle notes: Currently, reference patterns may only appear inside of other patterns so that the compiler can determine the region for the pointer type assigned to x. They also may not occur under a datatype pattern that has existential types unless there is a pointer pattern in-between.)
  • Bindings introduced: x is bound to the address of the expression being matched. Hence if matched against a value of type t in region `r, the type of x is t@`r.
  
  
  
• Numeric constant patterns
  • Syntax: An int, char, or float constant
  • Types for match: numeric types
  • Expressions matched: numeric values such that == applied to the value and the pattern yields true. (Standard C numeric promotions apply. Note that comparing floating point values for equality is usually a bad idea.)
  • Bindings introduced: none
  
  
  
• NULL constant patterns
  • Syntax: NULL
  • Types for match: nullable pointer types, including ? types
  • Expressions matched: NULL
  • Bindings introduced: none
  
  
  
• Enum patterns
  • Syntax: an enum constant
  • Types for match: the enum type containing the constant
  • Expressions matched: the constant
  • Bindings introduced: none
  
  
  
• Tuple patterns
  • Syntax: $(p1,...,pn[,...]) where p1,...,pn are patterns. The trailing comma and ellipses (...) are optional.
  • Types for match: if no ellipses, then tuple types with exactly n fields, where pi matches the type of the tuple's ith field. If the ellipses are present, then matches a tuple with at least n fields.
  • Expressions matched: tuples where the ith field matches pi for i between 1 and n.
  • Bindings introduced: bindings introduced by p1, ..., pn.
  
  
  
• Struct patterns
  • Syntax: There are three forms:
    • X(p1,...,pn[,...]) where X is the name of a struct with n fields and p1,...,pn are patterns. This syntax is shorthand for X{.f1 = p1, ..., .fn = pn [,...]} where fi is the ith field in X.
    • X{.f1 = p1, ..., .fn = pn [,...]} where the fields of X are f1, ..., fn but not necessarily in that order
    • {.f1 = p1, ..., .fn = pn [,...]} which is the same as above except that struct name X has been omitted.
    
    
    
  • Types for match: struct X (or instantiations when struct X is polymorphic) such that pi matches the type of fi for i between 1 and n. If the ellipses are not present, then each member of the struct must have a pattern.
  • Expressions matched: structs where the value in fi matches pi for i between 1 and n.
  • Bindings introduced: bindings introduced by p1,...,pn
  
  
  
• Tagged Union patterns
  • Syntax: There are two forms:
    • X{.fi = p} where the members of X are f1, ..., fn and fi is one of those members.
    • {{.f1 = p which is the same as above except that union name X has been omitted.
  • Types for match: union X (or instantiations when union X is polymorphic) such that p matches the type of fi.
  • Expressions matched: tagged unions where the last member written was fi and the value of that member matches p.
  • Bindings introduced: bindings introduced by p.
  
  
  
• Pointer patterns
  • Syntax: &p where p is a pattern
  • Types for match: pointer types, including ? types. Also datatype Foo @ (or instantiations of it) when the pattern is &Bar(p1,...,pn) and Bar is a variant of datatype Foo and pi matches the type of the ith value carried by Bar.
  • Expressions matched: non-null pointers where the value pointed to matches p. Note this explanation includes the case where the expression has type datatype Foo @ and the pattern is &Bar(p1,...,pn) and the current variant of the expression is ``pointer to Bar''.
  • Bindings introduced: bindings introduced by p
  
  
  
• Datatype patterns
  • Syntax: X if X is a variant that carries no values. Else X(p1,...,pn[,...]) where X is the name of a variant and p1, ..., pn are patterns. As with tuple and struct patterns, the ellipses are optional.
  • Types for match: datatype Foo (or instantiations of it).
  • Expressions matched: If X is non-value-carrying, then X. If X is value-carrying, then values created from the constructor X such that pi matches the ith field.
  • Bindings introduced: bindings introduced by p1,...,pn

5.3  Switch Statements

Restrictions

• You cannot implicitly ``fall-through'' to the next case. Instead, you must use the fallthru; statement, which has the effect of transferring control to the beginning of the next case. There are two exceptions to this restriction: First, adjacent cases with no intervening statement do not require a fall-through. Second, the last case of a switch does not require a fall-through or break.
• The cases in a switch must be exhaustive; it is a compile-time error if the compiler determines that it could be that no case matches. The rules for what the compiler determines are described below.
• A case cannot be unreachable. It is a compile-time error if the compiler determines that a later case may be subsumed by an earlier one. The rules for what the compiler determines are described below. (C almost has this restriction because case labels cannot be repeated, but Cyclone is more restrictive. For example, C allows cases after a default case.)
• The body of a switch statement must be a sequence of case statements and case statements can appear only in such a sequence. So idioms like Duff's device (such as ``switch(i%4) while(i-- >=0) { case 3: ... }'') are not supported.
• A constant case label must be a constant, not a constant expression. That is, case 3+4: is allowed in C, but not in Cyclone. Cyclone supports this feature with a separate construct: switch "C" (e) { case 3+4: ... }. This construct is much more like C's switch: The labels must be constant numeric expressions and fallthru is never required.

An Extension of C

  int f(int i) {
    switch(i) {
    case 0:  f(34); return 17;
    case 1:  return 17;
    default: return i;
    }
  }

Much More Powerful

  extern int f(int);}
  int g(int x, int y) {
    // return f(x)*f(y), but try to avoid using multiplication
    switch($(f(x),f(y))) {
    case $(0,_): fallthru;
    case $(_,0): return 0;
    case $(1,b): fallthru(b+1-1);
    case $(a,1): return a;
    case $(a,b): return a*b;
    }
  }

• It evaluates the pair $(f(x), f(y)) and stores the result on the stack.
• If f(x) returned 0, the first case matches, control jumps to the second case, and 0 is returned.
• Else if f(y) returned 0, the second case matches and 0 is returned.
• Else if f(x) returned 1, the third case matches, b is assigned the value f(y) returned, control jumps to the fourth case after assigning b+1-1 to a, and a (i.e., b + 1 - 1, i.e., b, i.e., f(y)) is returned.
• Else if f(y) returned 1, the fourth case matches, a is assigned the value f(x) returned, and a is returned.
• Else the last case matches, a is assigned the value f(x) returned, b is assigned the value f(y) returned, and a*b is returned.

Case Guards

extern int f(int);
int g(int a, int b) {
  switch ($(a,b-1)) {
  case $(0,y) && y > 1: return 1;
  case $(3,y) && f(x+y) == 7 : return 2;
  case $(4,72): return 3;
  default: return 3;
  }
}

Exhaustiveness and Useless-Case Checking

• In terms of exhaustiveness checking, the compiler acts as if any case guard might evaluate to false.
• In terms of exhaustiveness checking, numeric constants cannot make patterns exhaustive. Even if you list out all 256 characters, the compiler will act as though there is another possibility you have not checked.

  enum Color { Red, Green };
  void f(enum Color c1, enum Color c2) {
    switch ($(c1,c2)) {
    case $(Red,x): return;
    case $(x,Green): return;
    case $(Red,Green): return;
    default: return;
    }
  }

Rules for No Implicit Fall-Through

6  Type Inference

  _ x = malloc(sizeof(sometype_t));

  sometype_t * x = malloc(sizeof(sometype_t));

Syntax

• As part of a top-level variable or function's type.
• As part of a struct, union, datatype, or typedef declaration.

  void f(some_big_type * x, some_big_type @ y) {
  if(x != NULL) {
    y = (_ *@notnull) x;
  }

Semantics

  _ x = NULL;
  x = g();
  x->f;

Subtleties

Numeric Types

  int f() {
  char c = 1000;
  return c;
  }
  int g() {
  _ c = 1000; // compiler infers int
  return c;
  }
  int main() {
  printf("%d %d", f(), g());
  return 0;
  }

Order Matters

  void h1(int *@notnull c, int maybe) {
    _ a;
    if(maybe)
      a = c;
    else
      a = NULL;
  }

7  Polymorphism

8  Memory Management Via Regions

8.1  Introduction

Stack regions

As in C, local variables are allocated on the runtime stack; the stack grows when a block is entered, and it shrinks when the block exits. We call the area on the stack allocated for the local variables of a block the stack region of the block. A stack region has a fixed size---it is just large enough to hold the locals of the block, and no more objects can be placed into it. The region is deallocated when the block containing the declarations of the local variables finishes executing. With respect to regions, the parameters of a function are considered locals---when a function is called, its actual parameters are placed in the same stack region as the variables declared at the start of the function.

Lexical regions

Cyclone also has lexical regions, which are so named because, like stack regions, their lifetime is delimited by the surrounding scope. Unlike stack regions, however, you can can add new objects to a lexical region over time. You create a lexical region in Cyclone with a statement,

  region  identifier;  statement

This declares and allocates a new dynamic region, named identifier, and executes statement. After statement finishes executing, the region is deallocated. Within statement, objects can be added to the region, as we will explain below.

Typically, statement is a compound statement:

  { region identifier;
     statement1
    ...
     statementn
  }

The heap region

Cyclone has a special region called the heap. There is only one heap, whose type is denoted `H, and it is never deallocated. New objects can be added to the heap at any time (the heap can grow). Cyclone uses a garbage collector to automatically remove objects from the heap when they are no longer needed. You can think of garbage collection as an optimization that tries to keep the size of the heap small. (Alternatively, you can avoid garbage collection all together by specifying the -nogc flag when building the executable.)

Dynamic regions

Stack and lexical regions obey a strictly last-in-first-out (LIFO) lifetime discipline. This is often convenient for storing temporary data, but sometimes, the lifetime of data cannot be statically determined. Such data can be allocated in a dynamic region. A dynamic region supports deallocation at (essentially) any program point. However, before the data in a dynamic region may be accessed, the dynamic region must be opened. The open operation fails by throwing an exception if the dynamic region has already been freed. Note that each data access within a dynamic region does not require a check. Rather, you can open a given dynamic region once, access the data many times with no additional cost, and then exit the scope of the open. Thus, dynamic regions amortize the cost of checking whether or not data are still live and localize failure points.

The unique region

All of the regions mentioned thus far only permit deallocation en masse. Cyclone also defines the unique region, whose type is denoted `U, which allows objects to be deallocated individually, using the function ufree. For freeing objects to be safe, we only allow access to objects in `U via unique pointers. That is, only a single pointer may be used to access the object at any given time; this trivially guarantees that if the object is freed through its unique pointer, no other access to the object beyond that point is possible. Objects that become unreachable but are not freed manually will be freed by the garbage collector (assuming it's not removed with -nogc).

The reference-counted region

The reference-counted region, denoted `RC, also permits freeing individual objects. Unlike the unique region, multiple pointers to a single object are permitted, the number of which is tracked dynamically via a hidden reference count stored with the object. Additional pointers to an object are created explicitly via a call to alias_refptr, which increases the reference count. Individual pointers are removed via a call to drop_refptr; when the last pointer is removed (i.e. the reference count is 0), the object is freed. Like the unique region, objects that become unreachable will be freed by the garbage collector.

8.2  Allocation

• new expr evaluates expr, places the result into the heap, and returns a pointer to the result. It is roughly equivalent to

    t @ temp = malloc(sizeof(t));
    // where t is the type of expr
    *temp =  expr;
  

  For example, new 17 allocates space for an integer on the heap, initializes it to 17, and returns a pointer to the space. For another example, if we have declared

    struct Pair { int x; int y; };
  

  then new Pair(7,9) allocates space for two integers on the heap, initializes the first to 7 and the second to 9, and returns a pointer to the first.
  
  
• new array-initializer allocates space for an array, initializes it according to array-initializer, and returns a pointer to the first element. For example,

    let x = new { 3, 4, 5 };
  

  declares a new array containing 3, 4, and 5, and initializes x to point to the first element. More interestingly,

    new { for  identifier <  expr1 :  expr2 }
  

  is roughly equivalent to

    unsigned int sz =  expr1;
    t @ temp = malloc(sz * sizeof(t2)); // where t is the  type of expr
    for (int  identifier = 0;  identifier < sz;  identifier++)
      temp[ identifier] =  expr2;
  

  That is, expr₁ is evaluated first to get the size of the new array, the array is allocated, and each element of the array is initialized by the result of evaluating expr₂. expr₂ may use identifier, which holds the index of the element currently being initialized.
  
  For example, this function returns an array containing the first n positive even numbers:

    int *@fat n_evens(int n) {
      return new {for next < n :  2*(next+1)};
    }
  

  Note that:
  • expr₁ is evaluated exactly once, while expr₂ is evaluated expr₁ times.
  • expr₁ might evaluate to 0.
  • expr₁ might evaluate to a negative number. If so, it is implicitly converted to a very large unsigned integer; the allocation is likely to fail due to insufficient memory. Currently, this will cause a crash!!
  • Currently, for array initializers are the only way to create an object whose size depends on run-time data.
  
  
  
• malloc(sizeof(type)). Returns a @notnull pointer to an uninitialized value of type type.
  
  
• malloc(n*sizeof(type)) or malloc(sizeof(type)*n). The type must be a bits-only type (i.e., cannot contain pointers, tagged unions, zero-terminated values, etc.) If n is a compile-time constant expression, returns a @thin pointer with @numelts(n). If n is not a compile-time constant, returns a @fat pointer to the sequence of n uninitialized values.
  
  
• calloc(n,sizeof(type)). Similar to the malloc case above, but returns memory that is zero'd. Therefore, calloc supports types that are bits-only or zero-terminated.
  
  
• malloc(e) where e is an expression not of one of the above forms. If e is constant, returns a char *@numelts(e)@nozeroterm otherwise returns a char *@fat@nozeroterm.

  t * temp = malloc(sizeof(t));

  t *`U temp  =        malloc(sizeof(t));
  t *   temp2 = (t *`U)malloc(sizeof(t));

  t * temp = malloc(sizeof(t));
  ufree(temp);

• rnew(identifier) expr
• rnew(identifier) array-initializer
• rmalloc(identifier,sizeof(type))
• rmalloc(identifier,n*sizeof(type))
• rmalloc(identifier,sizeof(type)*n)
• rmalloc(identifier,e))
• rcalloc(identifier,n,sizeof(type))

8.3  Common Uses

void f1(int * x) {
  int * y = new 42;
  y = &x;
}

void f2(int x) {
  int * y = &x;
  y = new 42;
}

void f1(int * x) {
  int *`f1 y = new 42;
  y = &x;
}

void f(int * x, int * y);

void f(int *`r x, int *`r y);

int * f(int * x) { return x; }

int * f(int *`H x) { return x; }
int *`r f(int *`r x) {return x; }

typedef int * foo_t;
foo_t f(foo_t x) { return x; }

  $(int,int)*`r f(region_t<`r> r, int x, int y) { 
     return rnew(r) $(x,y);
  }

  void f2(region_t<`r> r,int x,int y,$(int,int)*`r *`s p){ 
    *p = rnew(r) $(7,9); 
  }

  { region rgn;
    $(int,int) *`rgn x = NULL; 
    f2(rgn,3,4,&x);
  }

  struct List<`a,`r>{`a hd; struct List<`a,`r> *`r tl;};
  typedef struct List<`a,`r> *`r list_t<`a,`r>;

  // return a fresh copy of the list in r2
  list_t<`a,`r2> rcopy(region_t<`r2> r2, list_t<`a> x) {
    list_t result, prev;

    if (x == NULL) return NULL;
    result = rnew(r2) List{.hd=x->hd,.tl=NULL};
    prev = result;
    for (x=x->tl; x != NULL; x=x->tl) {
      prev->tl = rnew(r2) List(x->hd,NULL);
      prev = prev->tl;
    }
    return result;
  }  
  list_t<`a> copy(list_t<`a> x) {
    return rcopy(heap_region, x);
  }

  // Return the length of a list. 
  int length(list_t x) {
    int i = 0;
    while (x != NULL) {
      ++i;
      x = x->tl;
    }
    return i;
  }

  list_t<`a,`r2> rcopy(region_t<`r2> r2, list_t<`a,`r1> x) {
    list_t<`a,`r2> result, prev;
    ...
  }
  list_t<`a,`H> copy(list_t<`a,`r> x) { ... }
  int length(list_t<`a,`r> x) { ... }

8.4  Unique Pointers

8.4.1  Simple Unique Pointers

  char *@fat`U buf = malloc(3*sizeof(char));
  buf[0] = 'h';
  buf[1] = 'i';
  buf[2] = '\0';
  ...
  ufree(buf);

 1  struct pair { int *`U x; int *`U y; } p;
 2  int *`U x = new 1;  // initializes x
 3  p.x = x;            // consumes x
 4  x = new 2;          // unconsumes x
 5  p.y = x;            // consumes x

  int *`U x = new 1;  // initializes x
  p.x = x;            // consumes x
  p.y = x;            // rejected! x has been consumed already

 1  struct pair { int *`U x; int *`U y; } p, q;
 2  p.x = new 1; p.y = new 2;
 3  q = p;              // consumes p.x and p.y

void foo(int *`U x) __attribute__((noconsume(1))) {
  *x = 1;
}
void bar() {
  int *`U x = malloc(sizeof(int));
  foo(x);
  ufree(x);
}

• No pointer arithmetic is allowed on unique pointers. This ensures that all unique pointers point to the beginning of the object, so that the allocator is not confused when a pointer is passed to ufree.
• Take the address of a unique pointer is not allowed. This is because doing so effectively creates an alias to the original pointer that cannot be easily tracked statically.
• Unique pointers cannot be stored within datatypes (though they can be stored in tagged unions). This is a shortcoming of the current flow analysis.

8.4.2  Nested Unique Pointers

int f(int *`U *`r x) {
  int *`U *`r y = x;  //x and y are aliases
  int *`U z = *y;
  ufree(z);
  return **x;  //accesses deallocated storage!
}

struct Queue<`a,`r> { 
  list_t<`a *`U,`r> front; 
  list_t<`a *`U,`r> rear; 
};
typedef struct Queue<`a,`r> *`r queue_t<`a,`r>;

`a *`U take(queue_t<`a> q) {
  if (q->front == NULL)
    throw &Empty_val;  // exception: def not shown
  else {
    let elem = NULL;
    elem :=: q->front->hd;
    q->front = q->front->tl;
    if (q->front == NULL) q->rear = NULL;
    return elem;
  }
}

8.4.3  Pattern Matching on Unique Pointers

struct pair { int x; int y; };
void foo() {
  struct pair @`U p = new pair(1,2);
  let &pair{.x=x, .y=y} = p;
  ufree(p);
}

struct Foo { int *`U x; int *`U y; };
void foo(struct Foo *`U p) {
  { let &Foo{.x=x, .y=y} = p; // consumes p->x and p->y
    ufree(x);                 // consumes x
  }                           // p->y is unconsumed
  ufree(p->y);                // p->y consumed
  ufree(p);                   // p consumed
}

void foo(struct Foo *`H p) {
 let &Foo{.x=x, .y=y} = p; // non-unique path!
 ...
}

void foo(struct Foo *`H p) {
 let x = p->x;
 let y = p->y;
 ...
}

8.4.4  Aliasing Unique Pointers

  char *@fat`U dst, *@fat`U src = ...
  { let alias <`r>char *@fat`r x = src; // consumes src
    memcpy(dst,x,numelts(x)); }
  // src unconsumed
  ...
  ufree(src);

  void foo(list_t<`a,`U> l) {
    alias <`r> x = (list_t<`a,`r>)l;
    x->tl = x; // unsound: creates alias!
  }

  int length(clist_t<`a,`r> l) {
    int len = 0;
    while (l != NULL) {
      len++;
      l = l->tl;
    }
    return len;
  }

  int foo() {
    list_t<int,`U> l = new List(1,new List(2,NULL));
    let alias <`r>clist_t<int,`r> x = l;
    return length(x);
  }

  int foo() {
    list_t<int,`U> l = new List(1,new List(2,NULL));
    return length(l);
  }

8.4.5  Polymorphism

  $(int @`r, int @`r) make_pair(region_t<`r> rgn) {
    int @x = rnew (rgn) 1;
    return $(x, x);
  }

  $(int @,int@) pair = make_pair(heap_region);

  $(int @`U,int @`U) pair = make_pair(unique_region);
  ufree(pair[0]);
  int x = pair[1]; // error! dereferences freed pointer

  $(int @`r, int @`r) make_pair(region_t<`r::R> rgn) {
    int @x = rnew (rgn) 1;
    return $(x, x);
  }

  struct List<`a,`r::TR>{`a hd; struct List<`a,`r> *`r tl;};
  typedef struct List<`a,`r> *`r list_t<`a,`r>;

  // return a fresh copy of the list in r2
  list_t<`a,`r2> rcopy(region_t<`r2::TR> r2, list_t<`a> x) {
    if (x == NULL) return NULL;
    else {
      list_t rest = rcopy(r2,x->tl);
      return rnew(r2) List{.hd=x->hd,.tl=rest};
    }
  }
  list_t<`a> copy(list_t<`a> x) {
    return rcopy(heap_region, x);
  }

1. The definition of List has been generalized so that its `r region variable now has kind TR. This implies that lists can point into any region, whether unique or aliasable. Actually, we need not include the ::TR kind annotation on region type variables in typedefs; this is the default (since it allows instantation of any region parameter).
2. The region handle r2 now has kind TR, rather than the default R. This means that we can pass in any region handle, and thus copy a list into any kind of region.
3. We have made rcopy's implementation recursive. This was necessary to avoid creating aliases to the newly created list. In particular, if we were to have used a prev pointer as in the version from Section 8.3100Common Usessubsection.8.3, we would have two pointers to the last-copied element: the tl field of the element before it in the list, and the current iterator variable prev. The use of recursion allows us to iterate to the end of the list and construct it back to front, in which no aliases are required. The cost is we need to do extra stack allocation. This example illustrates that it is sometimes difficult to program using no-alias pointers. This is why, in cases other than allocation, we would prefer to use the alias construct to allow temporary aliasing.

  $(`a,`a) pair(`a x) {
    return $(x,x);
  }

  int @`U p = new 1;
  $(int @`U,int @`U) pair = pair(p);
  ufree(pair[0]);
  int x = pair[1]; // error! dereferences freed pointer

  $(`a,`a) pair(`a::B x) {
    return $(x,x);
  }

8.5  Reference-counted Pointers

  int refptr_count(`a::TA ?`RC ptr)
    __attribute__((noconsume(1)));

  `a ?`RC alias_refptr(`a::TA ?`RC ptr)
    __attribute__((noconsume(1)));

  void drop_refptr(`a::TA ?`RC ptr);

8.6  Dynamic Regions

int main() {
  // Create a new dynamic region
  let NewDynamicRegion{<`r> key} = new_ukey();

  // At this point, we refer to the region `r to
  // specify types, but we cannot actually access
  // `r (i.e. it's not in our "static capability,"
  // a concept explained later)

  list_t<int,`r> x = NULL;

  // We can access x by opening the region, which
  // temporarily consumes the key
  { region h = open(key);
    x = rnew(h) List(3,x);
  }

  // Now we can access the key again, but not x.
  // So we have to open the region to increment
  // its contents
  { region h = open(key);
    int i = x->hd + 1;
    x = rnew (h) List(i,x);
  }

  // Finally, destroy the key and the region
  free_ukey(key);
}

struct MyContainer { <`r>
  uregion_key_t<`r> key;
  list_t<int,`r> data;
} *`U global = NULL;

int main() {
  // allocate a dynamic region, and create a list
  let NewDynamicRegion{<`r> key} = new_ukey();
  list_t<int,`r> x = NULL;
  { region h = open(key);
    x = rnew(h) List(3,x);
  }

  // Stick the key and list in a global data
  // structure. We've now lost direct access to
  // the key and x.
  global = new MyContainer{key,x};

  // But we can regain it by swapping for the
  // container.
  struct MyContainer *`U p = NULL;
  global :=: p;

  // Now we can use it as above
  let MyContainer{<`r2> key2, data2} = *p;
  list_t<int,`r2> d = data2;
  { region h = open(key2);
    int i = d->hd + 1;
    d = rnew (h) List(i,d);
  }
}

8.7  Type-Checking Regions

• Use compile-time region names. Syntactically these are just type variables, but they are used differently.
• Decorate each pointer type and handle type with one region name.
• Decorate each program point with a (finite) set of region names. We call the set the point's capability.
• To dereference a pointer (via *, ->, or subscript), the pointer's type's region name must be in the program point's capability. Similarly, to use a handle for allocation, the handle type's region name must be in the capability.
• Enforce a type system such that the following is impossible: A program point P's capability contains a region name `r that decorates a pointer (or handle) expression expr that, at run time, points into a region that has been deallocated and the operation at P dereferences expr.

8.7.1  Region Names

• If a block (blocks create stack regions) has label L, then the region-name for the block is `L.
• If a block has no label, the compiler makes up a fresh region-name for the block.
• In region r <`foo> s, the region-name for the construct is `foo.
• In region r s, the region-name for the construct is `r.
• In region h = open(k) s, the region-name for the construct is `r, assuming k has type region_key_t<`r,_> (where _ is some other region name of no consequence).

8.7.2  Capabilities

• `H, `U, and `RC
• The effect corresponding to the function's prototype. Briefly, any region name in the prototype (or inserted by the compiler due to an omission) is in the corresponding effect. Furthermore, for each type variable `a that appears (or is inserted), ``regions(`a)'' is in the corresponding effect. This latter effect roughly means, ``I don't know what `a is, but if you instantiate with a type mentioning some regions, then add those regions to the effect of the instantiated prototype.'' This is necessary for safely type-checking calls that include function pointers.
• The region names for the blocks and ``region r s'' statements that contain the program point

8.7.3  Assignment and Outlives

• Every region outlives itself.
• `U outlives `H, and every region name of UR or R kind.
• `RC outlives `H, and every region name of TR or R kind.
• `H outlives every region name of R kind.
• Region names for inner blocks outlive region names for outer blocks.
• For regions in function prototypes, you can provide explicit ``outlives'' as in this example:

  void f(int *`r1*`r2 x,int *`r3 y; {`r2} > `r1, {`r3} > `r2);
  

  This says that `r1 outlives `r2 and `r2 outlives `r3. The body will be checked under these assumptions. Calls to f will type-check only if the compiler knows that the region names of the actual arguments obey the outlives assumptions.
  
  There are some restrictions on specifying outlives relationships when considering region names of UR or TR kind, though these rarely come up in practice. In particular:
  • Region names of R kind can only outlive region names R kind.
  • Region names of UR kind can only outlive region names R kind or UR kind.
  • Region names of TR kind can only outlive region names R kind or TR kind.

8.7.4  Type Declarations

  struct List<`a,`r>{`a hd; struct List<`a,`r> *`r tl;};

8.7.5  Function Calls

8.7.6  Explicit and Default Effects

9  Namespaces

  namespace Foo { 
    int x = 0; 
    int f() { return x; }  
  }

  namespace Bar {  
    using Foo { 
      int g() { return f(); } 
    } 
    int h() { return Foo::f(); } 
  }

• The current implementation translates qualified Cyclone variables to C identifiers very naively: each :: is translated to _ (underscore). This translation is wrong because it can introduce clashes that are not clashes in Cyclone, such as in the following:

    namespace Foo { int x = 7; }
    int Foo_x = 9;
  

  So avoid prefixing your identifiers with namespaces in your program. We intend to fix this bug in a future release.
  
  
• Because #include is defined as textual substitution, the following are usually very bad ideas: Having ``namespace Foo;'' or ``using Foo;'' at the top level of a header file. After all, you will be changing the identifiers produced or the identifiers available in every file that includes the header file. Having #include directives within the scope of namespace declarations. After all, you are changing the names of the identifiers in the header file by (further) qualifying them. Unfortunately, the current system uses the C pre-processor before looking at the code, so it cannot warn you of these probable errors.
  
  In short, you are advised to not use the ``semicolon syntax'' in header files and you are advised to put all #include directives at the top of files, before any namespace or using declarations.
  
  
• The translation of identifiers declared extern "C" is different. Given

    namespace Foo { extern "C" int x; }
  

  the Cyclone code refers to the global variable as Foo::x, but the translation to C will convert all uses to just x. The following code will therefore get compiled incorrectly (f will return 4):

    namespace Foo { extern "C" int x; }
    int f() {
      int x = 2;
      return x + Foo::x;
    }
  

10  Varargs

extern "C" void foo(int x, ...);
void g() { 
  foo(3, 7, "hi", 'x');
}

void foo(int x, ...string_t args);
void g() {
  foo(17, "hi", "mom");
}

list_t<`a> list(... `a argv) {
  list_t result = NULL;
  for (int i = numelts(argv) - 1; i >= 0; i--) 
    result = new List{argv[i],result};
  return result;
}

extern datatype PrintArg<`r::R> {
  String_pa(const char ? *@notnull @nozeroterm`r);
  Int_pa(unsigned long);
  Double_pa(double);
  LongDouble_pa(long double);
  ShortPtr_pa(short *@notnull `r);
  IntPtr_pa(unsigned long *@notnull `r);
};
typedef datatype PrintArg<`r> *@notnull `r parg_t<`r>;
int printf(const char *@fat fmt, ... inject parg_t);

11  Definite Assignment

• Many idioms require declaring variables in a wider scope than is convenient for initializing the variable.
• C code, which we wish to port to Cyclone, is full of separated allocation and initialization, including all heap-allocated storage (i.e., malloc).

  extern int maybe();
  int f() {
    int *x, *y, *z;
    if(maybe())
      x = new 3;
    else
      x = new 4;
    while(1) {
      y = x;
      break;
    }
    if(z = new maybe() && maybe() && q = new maybe())
      return q;
    else
      return z;
  }

  extern int maybe();
  int f() {
    int * x = new 1;
    int * y;
    int b = maybe();
    if(b) 
      y = 2;
    if(b)
     return y;
   return 0;
  }

  extern int maybe();
  int f() {
    int * x;
    int * z;
    int ** y;
    if(maybe()) {
      x = new 3;
      y = &x;
    } else {
      y = &z;
      z = new 3;
    }
    return *y;
  }

  extern int maybe();
  int f() {
    int * x;
    int * z;
    int ** y;
    if(maybe()) {
      y = &x;
    } else {
      y = &z;
    }
    x = new 3;
    z = new 3;
    return *y;
  }

  struct IntPair { int x; int y; };
  struct IntPair * same(int z) {
    struct IntPair * ans = 
          (struct IntPair *)malloc(sizeof(struct IntPair));
    ans->x = z;
    ans->y = z;
    return ans;
  }

  struct B { int * x; $(int*,int*) y;}; 
  void f() {
    struct B b;
    struct B * bp = malloc(sizeof(B));
    ...
  }

  struct B * bp2;                some_fun(bp);                      
  if(maybe()) 
     bp2 = bp;

  int f() {
    int * x, int *y;
    int **p1;
    if(maybe())
     p1 = &x;
    else
     p1 = &y;
    *p1 = new 7;
    return *p1;
  }

  list_t<`a,`H> copy(list_t<`a> x) {
    struct List *@notnull result, *@notnull prev;

    if (x == NULL) return NULL;
    result = new List{.hd=x->hd,.tl=NULL};
    prev = result;
    for (x=x->tl; x != NULL; x=x->tl) {
      struct List *@notnull temp = malloc(sizeof(struct List));
      temp->hd = x->hd;
      temp->tl = NULL;
      prev->tl = temp;
      prev = temp;
    }
    return result;
  }  

  list_t<`a,`r2> rcopy(region_t<`r2> r2, list_t<`a> x) {
    struct List *@notnull result, *@notnull prev;

    if (x == NULL) return NULL;
    result = rnew(r2) List{.hd=x->hd,.tl=NULL};
    prev = result;
    for (x=x->tl; x != NULL; x=x->tl) {
      prev->tl = malloc(sizeof(struct List));
      prev->tl->hd = x->hd;
      prev->tl->tl = NULL;
      prev = prev->tl;
    }
    return result;
  }  

12  Advanced Features

12.1  Existential Types

  struct T { <`a> `a f1; `a f2; };

  struct T x = T{new 3, new 4};

  struct T x = T{<int*@notnull> new 3, new 4};

  void f(struct T t) {
    let T{<`b> x,y} = t;
    x = y;
  }

  int f1(int x, int y) { return x+y; }
  int f2(string x, int y) {printf("%s",x); return y; }
  struct T<`r::R> {<`a> : regions(`a) > `r 
    `a f1; 
    int f(`a, int); 
  };
  void g(bool b) {
    struct T<`H> t;
    if(b)
      t = Foo(37,f1);
    else
      t = Foo("hi",f2);
    let T{<`b> arg,fun} = t;
    `b x = arg;
    int (*f)(`b,int) = fun;
    f(arg,19);
  }

12.2  The Truth About Effects, Capabilities, and Region Bounds

• {} is the empty set. At most the heap region is accessed by an expression having this effect.
• {`r} is the set containing exactly the region name `r.
• e1 + e2 is the set containing the effects e1 and e2. That is, we write + for set-union.
• regions(t), where t is a type is the set containing all of the region names contained in t and regions(`a) for all type variables `a contained in t.

`a id(`a x; {}) { return x; }

  
struct T<`r::R> {<`a> : regions(`a) > `r 
  `a f1; 
  int f(`a, int); 
};

12.3  Interprocedural Memory Initialization

void f(int *@notnull*@notnull x) __attribute__((initializes(1))) { 
  x = new (new 0); 
  return x; 
}

1. The parameter is initialized only if the return value satisfies some predicate; for example, it is 0.
2. The caller can pass NULL, meaning do not initialize through this parameter.

A  Porting C code to Cyclone

A.1  Semi-Automatic Porting

1.   #include <stdio.h>
2. 
3.   void foo(char *s) {
4.     printf(s);
5.   }
6. 
7.   int main(int argc, char **argv) {
8.     argv++;
9.     for (argc--; argc >= 0; argc--, argv++)
10.      foo(*argv);
11.  }

  cyclone -port foo.cyc > rewrites.txt

  foo.cyc(5:14-5:15): insert `?' for `*'
  foo.cyc(9:24-9:25): insert `?' for `*'
  foo.cyc(9:25-9:26): insert `?' for `*'

  rewrite -port foo.cyc > rewrites.txt

#include <stdio.h>

__cyclone_port_on__;

void foo(char ?s) { 
  printf(s);
}

int main(int argc, char ??argv) {
  argv++;
  for (argc--; argc >= 0; argc--, argv++) 
    foo(*argv);
}
__cyclone_port_off__;

A.2  Manually Translating C to Cyclone

• Change pointer types to fat pointer types where necessary.
• Use comprehensions to heap-allocate arrays.
• Use tagged unions for unions with pointers.
• Initialize variables.
• Put breaks or fallthrus in switch cases.
• Replace one temporary with multiple temporaries.
• Connect argument and result pointers with the same region.
• Insert type information to direct the type-checker.
• Copy ``const'' code or values to make it non-const.
• Get rid of calls to free, calloc, etc.
• Use polymorphism or tagged unions to get rid of void*.
• Rewrite the bodies of vararg functions.
• Use exceptions instead of setjmp.

Change pointer types to fat pointer types where necessary.

Ideally, you should examine the code and use thin pointers (e.g., int* or better int*@notnull) wherever possible as these require fewer run-time checks and less storage. However, recall that thin pointers do not support pointer arithmetic. In those situations, you'll need to use fat pointers (e.g., int*@fat which can also be written as int?). A particularly simple strategy when porting C code is to just change all pointers to fat pointers. The code is then more likely to compile, but will have greater overhead. After changing to use all fat pointers, you may wish to profile or reexamine your code and figure out where you can profitably use thin pointers.

Use comprehensions to heap-allocate arrays.

Cyclone provides limited support for malloc and separated initialization but this really only works for bits-only objects. To heap- or region-allocate and initialize an array that might contain pointers, use new or rnew in conjunction with array comprehensions. For example, to copy a vector of integers s, one might write:

  int *@fat t = new {for i < numelts(s) : s[i]};

Use tagged unions for unions with pointers.

Cyclone only lets you read members of unions that contain ``bits'' (i.e., ints; chars; shorts; floats; doubles; or tuples, structs, unions, or arrays of bits.) So if you have a C union with a pointer type in it, you'll have to code around it. One way is to simply use a @tagged union. Note that this adds hidden tag and associated checks to ensure safety.

Initialize variables.

Top-level variables must be initialized in Cyclone, and in many situations, local variables must be initialized. Sometimes, this will force you to change the type of the variable so that you can construct an appropriate initial value. For instance, suppose you have the following declarations at top-level:

struct DICT; 
struct DICT *@notnull new_dict();
struct DICT *@notnull d;
void init() {
  d = new_dict();
}

Here, we have an abstract type for dictionaries (struct Dict), a constructor function (new_dict()) which returns a pointer to a new dictionary, and a top-level variable (d) which is meant to hold a pointer to a dictionary. The init function ensures that d is initialized. However, Cyclone would complain that d is not initialized because init may not be called, or it may only be called after d is already used. Furthermore, the only way to initialize d is to call the constructor, and such an expression is not a valid top-level initializer. The solution is to declare d as a ``possibly-null'' pointer to a dictionary and initialize it with NULL:

struct DICT; 
struct DICT *nonnull new_dict();
struct DICT *d;
void init() {
  d = new_dict();
}

Of course, now whenever you use d, either you or the compiler will have to check that it is not NULL.

Put breaks or fallthrus in switch cases.

Cyclone requires that you either break, return, continue, throw an exception, or explicitly fallthru in each case of a switch.

Replace one temporary with multiple temporaries.

Consider the following code:

void foo(char * x, char * y) {
  char * temp;
  temp = x;
  bar(temp);
  temp = y;
  bar(temp);
}

When compiled, Cyclone generates an error message like this:

type mismatch: char *@zeroterm #0  != char *@zeroterm #1 

The problem is that Cyclone thinks that x and y might point into different regions (which it named #0 and #1 respectively), and the variable temp is assigned both the value of x and the value of y. Thus, there is no single region that we can say temp points into. The solution in this case is to use two different temporaries for the two different purposes:

void foo(char * x, char * y) {
  char * temp1;
  char * temp2;
  temp1 = x;
  bar(temp1);
  temp2 = y;
  bar(temp2);
}

Now Cyclone can figure out that temp1 is a pointer into the region #0 whereas temp2 is a pointer into region #1.

Connect argument and result pointers with the same region.

Remember that Cyclone assumes that pointer inputs to a function might point into distinct regions, and that output pointers, by default point into the heap. Obviously, this won't always be the case. Consider the following code:

int *foo(int *x, int *y, int b) {
  if (b)
    return x;
  else
    return y;
}

Cyclone complains when we compile this code:

returns value of type int *#0  but requires int *
        #0 and `H failed to unify. 
returns value of type int *#1  but requires int *
        #1 and `H failed to unify. 

The problem is that neither x nor y is a pointer into the heap. You can fix this problem by putting in explicit regions to connect the arguments and the result. For instance, we might write:

int *`r foo(int *`r x, int *`r y, int b) {
  if (b)
    return x;
  else
    return y;
}

and then the code will compile. Of course, any caller to this function must now ensure that the arguments are in the same region.

Insert type information to direct the type-checker.

Cyclone is usually good about inferring types. But sometimes, it has too many options and picks the wrong type. A good example is the following:

void foo(int b) {
  printf("b is %s", b ? "true" : "false");
} 

When compiled, Cyclone warns:

(2:39-2:40): implicit cast to shorter array

The problem is that the string "true" is assigned the type const char ?{5} whereas the string "false" is assigned the type const char ?{6}. (Remember that string constants have an implicit 0 at the end.) The type-checker needs to find a single type for both since we don't know whether b will come out true or false and conditional expressions require the same type for either case. There are at least two ways that the types of the strings can be promoted to a unifying type. One way is to promote both to char? which would be ideal. Unfortunately, Cyclone has chosen another way, and promoted the longer string ("false") to a shorter string type, namely const char ?{5}. This makes the two types the same, but is not at all what we want, for when the procedure is called with false, the routine will print

b is fals

Fortunately, the warning indicates that there might be a problem. The solution in this case is to explicitly cast at least one of the two values to const char ?:

void foo(int b) {
  printf("b is %s", b ? ((const char ?)"true") : "false");
} 

Alternatively, you can declare a temp with the right type and use it:

void foo(int b) {
  const char ? t = b ? "true" : "false"
  printf("b is %s", t);
} 

The point is that by giving Cyclone more type information, you can get it to do the right sorts of promotions.

Copy ``const'' code or values to make it non-const.

Cyclone takes const seriously. C does not. Occasionally, this will bite you, but more often than not, it will save you from a core dump. For instance, the following code will seg fault on most machines:

void foo() {
  char ?x = "howdy"
  x[0] = 'a';
}

The problem is that the string "howdy" will be placed in the read-only text segment, and thus trying to write to it will cause a fault. Fortunately, Cyclone complains that you're trying to initialize a non-const variable with a const value so this problem doesn't occur in Cyclone. If you really want to initialize x with this value, then you'll need to copy the string, say using the dup function from the string library:

void foo() {
  char ?x = strdup("howdy");
  x[0] = 'a';
}

Now consider the following call to the strtoul code in the standard library:

extern unsigned long strtoul(const char ?`r n, 
                             const char ?`r*`r2 endptr,
                             int base);
unsigned long foo() {
  char ?x = strdup("howdy");
  char ?*e = NULL;
  return strtoul(x,e,0);
}

Here, the problem is that we're passing non-const values to the library function, even though it demands const values. Usually, that's okay, as const char ? is a super-type of char ?. But in this case, we're passing as the endptr a pointer to a char ?, and it is not the case that const char ?* is a super-type of char ?*. In this case, you have two options: Either make x and e const, or copy the code for strtoul and make a version that doesn't have const in the prototype.

Get rid of calls to free, calloc etc.

There are many standard functions that Cyclone can't support and still maintain type-safety. An obvious one is free() which releases memory. Let the garbage collector free the object for you, or use region-allocation if you're scared of the collector. Other operations, such as memset, memcpy, and realloc are supported, but in a limited fashion in order to preserve type safety.

Use polymorphism or tagged unions to get rid of void*.

Often you'll find C code that uses void* to simulate polymorphism. A typical example is something like swap:

void swap(void **x, void **y) {
  void *t = x;
  x = y;
  y = t;
}

In Cyclone, this code should type-check but you won't be able to use it in many cases. The reason is that while void* is a super-type of just about any pointer type, it's not the case that void** is a super-type of a pointer to a pointer type. In this case, the solution is to use Cyclone's polymorphism:

void swap(`a *x, `a *y) {
  `a t = x;
  x = y;
  y = t;
}

Now the code can (safely) be called with any two (compatible) pointer types. This trick works well as long as you only need to ``cast up'' from a fixed type to an abstract one. It doesn't work when you need to ``cast down'' again. For example, consider the following:

int foo(int x, void *y) {
  if (x)
   return *((int *)y);
  else {
    printf("%s\n",(char *)y);
    return -1;
  }
}

The coder intends for y to either be an int pointer or a string, depending upon the value of x. If x is true, then y is supposed to be an int pointer, and otherwise, it's supposed to be a string. In either case, you have to put in a cast from void* to the appropriate type, and obviously, there's nothing preventing someone from passing in bogus cominations of x and y. The solution in Cylcone is to use a tagged union to represent the dependency and get rid of the variable x:

@tagged union IntOrString { 
  int Int;
  const char *@fat String;
};
typedef union IntOrString i_or_s;
int foo(i_or_s y) {
  switch (y) {
  case {.Int = i}:  return i;
  case {.String = s}:  
    printf("%s\n",s);
    return -1;
  }
}

Rewrite the bodies of vararg functions.

See the section on varargs for more details.

Use exceptions instead of setjmp.

Many uses of setjmp/longjmp can be replaced with a try-block and a throw. Of course, you can't do this for things like a user-level threads package, but rather, only for those situations where you're trying to ``pop-out'' of a deeply nested set of function calls.

A.3  Interfacing to C

  extern "C" double acos(double);

extern "C" {
  double acos(double);
  float  acosf(float);
  double acosh(double);
  float  acoshf(float);
  double asin(double);
}

extern "C include" {
  char peek(unsigned int i) {
    return *((char *)i);
  }

  void poke(unsigned int i, char c) {
    *((char *)i) = c;
  }
} export {
  peek, poke;
}

B  Frequently Asked Questions

What does $(type1,type2) mean? What does $(expr1, expr2) mean?

Cyclone has tuples, which are anonymous structs with fields numbered 0, 1, 2, .... For example, $(int,string_t) is a pair of an int and a string_t. An example value of this type is $(4,"cyclone"). To extract a field from a tuple, you use array-like notation: you write x[0], not x.0.

What does int @ mean?

In Cyclone @ is a pointer that is guaranteed not to be NULL. The Cyclone compiler guarantees this through static or dynamic checks. For example,

  int *x = NULL;

is not an error, but

  int @x = NULL;

is an error. Note that ``int @'' is shorthand for the more verbose ``int *@notnull''.

What does int *{37} mean?

This is the type of (possibly-null) pointers to a sequence of at least 37 integers, which can also be written as ``int *@numelts(37)''. The extra length information is used by Cyclone to prevent buffer overflows. For example, Cyclone will compile x[expr] into code that will evaluate expr, and check that the result is less than 37 before accessing the element. Note that int * is just shorthand for int *{1}. Currently, the expression in the braces must be a compile-time constant.

What does int *`r mean?

This is the type of a pointer to an int in region `r. A region is just a group of objects with the same lifetime---all objects in a region are freed at once. Cyclone uses this region information to prevent dereferencing a pointer into a previously freed region. Regions can have a ``nested'' structure, for example, if the region for a function parameter is a variable, then the function may assume that the parameter points into a region whose lifetime includes the lifetime of the function.

What does `H mean?

This is Cyclone's heap region: objects in this region cannot be explicitly freed, only garbage-collected. Effectively, this means that pointers into the heap region can always be safely dereferenced; conceptually, objects in the heap last ``forever,'' since they are always available if needed; garbage collection is like an optimization that frees objects after they are no longer needed.

What does int @{37}`r mean?

A pointer can come with all or none of the nullity, bound, and region annotation. This type is the type of non-null pointers to at least 37 consecutive integers in region `r. When the bound is omitted it default to 1.

What is a pointer type's region when it's omitted?

Every pointer type has a region; if you omit it, the compiler puts it in for you implicitly. The region added depends on where the pointer type occurs. In function arguments, a new region variable is used. In function results and type definitions (inlcuding typedef), the heap region (`H) is used. In function bodies, the compiler looks at the uses (using unification) to try to determine a region.

What does int ? mean?

The ? a special kind of pointer that carries along bounds information. It is a ``questionable'' pointer: it might be NULL or pointing out of bounds. An int ? is a pointer to an integer, along with some information that allows Cyclone to check whether the pointer is in bounds at run-time. These are the only kinds of pointers that you can use for pointer arithmetic in Cyclone.

What does `a mean?

`a is a type variable. Type variables are typically used in polymorphic functions. For example, if a function takes a parameter of type `a, then the function can be called with a value of any suitable type. If there are two arguments of type `a, then any call will have to give values of the same type for those parameters. And if the function returns a type `a, then it must return a result of the same type as the the argument. Syntactically, a type variable is any identifier beginning with ` (backquote).

What is a ``suitable'' type for a type variable?

The last question said that a type variable can stand for a ``suitable'' type. Unfortunately, not all types are ``suitable.'' Briefly, the ``suitable'' types are those that fit into a general-purpose machine register, typically including int, and pointers. Non-suitable types include float, struct types (which can be of arbitrary size), tuples, and questionable pointers. Technically, the suitable types are the types of ``box kind,'' described below.

How do I cast from void *?

You can't do this in Cyclone. A void * in C really does not point to void, it points to a value of some type. However, when you cast from a void * in C, there is no guarantee that the pointer actually points to a value of the expected type. This can lead to crashes, so Cyclone doesn't permit it. Cyclone's polymorphism and tagged unions can often be used in places where C needs to use void *, and they are safe.

What does _ (underscore) mean in types?

Underscore is a ``wildcard'' type. It stands for some type that the programmer doesn't want to bother writing out; the compiler is expected to fill in the type for the programmer. Sometimes, the compiler isn't smart enough to figure out the type (you will get an error message if so), but usually there is enough contextual information for the compiler to succeed. For example, if you write

  _ x = new Pair(3,4);

the compiler can easily infer that the wildcard stands for struct Pair @. In fact, if x is later assigned NULL, the compiler will infer that x has type struct Pair * instead.

Note that _ is not allowed as part of top-level declarations.

What do `a::B, `a::M, `a::A, `a::R, `a::UR, `a::TR and `a::E mean?

Types are divided into different groups, which we call kinds. There are four ``normal'' kinds: B (for Box), M (for Memory), A (for Any), and E (for Effect); and three ``region'' kinds: R (for Region), UR (for unique region), and TR (for either regular or unique region). The notation typevar::kind says that a type variable belongs to a kind. A type variable can only be instantiated by types that belong to its kind.

Box types include int, long, region_t, tag_t, enums, and non-@fat pointers. Memory types include all box types, void, char, short, long long, float, double, arrays, tuples, datatype and @extensible datatype variants, @fat pointers, and non-abstract structs and unions. Any types include all types that don't have kind R, UR, TR, or E. For the region types, R indicates ``normal'' regions like the heap, stack, and dynamic regions; UR indicates the unique region (i.e. only `U or an alias of it has kind UR); and TR indicates either; UR and TR kinds are used generally only in certain region-polymorphic functions; see Section 8.4.5117Polymorphismsubsubsection.8.4.5. Effect types are sets of regions (these are explained elsewhere).

What does it mean when type variables don't have explicit kinds?

Every type variable has a kind, but usually the programmer doesn't have to write it down. In function prototypes, the compiler will infer the most permissive kind. For example,

  void f(`a *`b x, `c * y, `a z);

is shorthand for

void f(`a::B *`b::R x, `c::M * y, `a::B z)

In type definitions, no inference is performed: an omitted kind is shorthand for ::B. For example,

struct S<`a,`r::R> { `a *`r x; };

is shorthand for

struct S<`a::B,`r::R> { `a *`r x;};

but

struct S<`a,`r>{`a *`r x;};

is not.

What does struct List<`a,`r::R> mean?

struct List takes a type of box kind and a region and produces a type. For example, struct List<int, `H> is a type, and struct List<struct List<int,`H>@, `H> is a type. struct List<`a,`r::R> is a list whose elements all have type `a and live in region `r.

What is a @tagged union?

In C, when a value has a union type, you know that in fact it has one of the types of the union's fields, but there is no guarantee which one. This can lead to crashes in C. Cyclone's @tagged unions are like C unions with some additional information (a tag) that lets the Cyclone compiler determine what type the underlying value actually has, thus helping to ensure safety.

What is abstract?

abstract is a storage-class specifier, like static or extern. When attached to a top-level type declaration, it means that other files can use the type but cannot look at the internals of the type (e.g., other files cannot access the fields of an abstract struct). Otherwise, abstract has the same meaning as the auto (default) storage class. Hence abstract is a way to state within a Cyclone file that a type's representation cannot be exported.

What are the Cyclone keywords?

In addition to the C keywords, the following have special meaning and cannot be used as identifiers: abstract, catch, datatype, fallthru, let, malloc, namespace, new, NULL, region_t, regions, rmalloc, rnew, throw, try, using. As in gcc, __attribute__ is reserved as well.

What are namespace and using?

These constructs provide a convenient way to help avoid name clashes. namespace X prepends X:: to the declarations in its body (rest of file in case of namespace X;) and using X makes the identifiers prepended with X:: available without having to write the X::.

What is fallthru?

In Cyclone, you cannot implicitly fall through from one switch case to the next (a common source of bugs in C). Instead, you must explicitly fall through with a fallthru statement. So, to port C code, place fallthru; at the end of each case that implicitly falls through; note that fallthru may not appear in the last case of a switch.

fallthru is useful for more than just catching bugs. For instance, it can appear anywhere in a case; its meaning is to immediately goto the next case. Second, when the next case of the switch has pattern variables, a fallthru can (and must) be used to specify expressions that will be bound to those variables in the next case. Hence fallthru is more powerful (but more verbose) than ``or patterns'' in ML.

What is new?

new expr allocates space in the heap region, initializes it with the result of evaluating expr, and returns a pointer to the space. It is roughly equivalent to

 type @temp = malloc(sizeof(type));
 *temp = expr;

where type is the type of expr. You can also write

  new { for i < expr1 : expr2 }

to heap-allocate an array of size expr₁ with the i^th element initialized to expr₂ (which may mention i).

How do I use tuples?

A tuple type is written $(type₀, ..., type_n). A value of the type is constructed by $(expr₀, ..., expr_n), where expr_i has type type_i. If expr has type $(type₀, ..., type_n), you can extract the component i using expr[i]. The expression in the brackets must be a compile-time constant. In short, tuples are like anonymous structs where you use expr[i] to extract fields instead of expr.i. There is no analogue of the -> syntax that can be used with pointers of structs; if expr has type $(type₁, ..., type_n) *, you can extract component i by (*expr)[i].

What is {for i < expr1 : expr2}?

This is an array initializer. It can appear where array initializers appear in C, and it can appear as the argument to new. It declares an identifier (in this case, i) whose scope is expr₂. expr₁ is an expression which is evaluated to an unsigned integer giving the desired size of the array. The expression expr₂ is evaluated expr₁ times, with i ranging over 0, 1, ..., expr₁-1; the result of each evaluation initializes the i^th element of the array.

The form new {for i < expr₁ : expr₂} allocates space for a new array and initializes it as just described. This form is the only way to create arrays whose size depends on run-time information. When {for i < expr₁ : expr₂} is not an argument to new, expr₁ must be constant and expr₂ may not mention i. This restriction includes all uses at top-level (for global variables).

How do I throw and catch exceptions?

A new exception is declared as in

  datatype exn { MyExn };

The exception can be thrown with the statement

  throw MyExn;

You can catch the expression with a try/catch statement:

  try  statement1 catch { case MyExn:  statement2 }

If statement₁ throws an MyExn and no inner catch handles it, control transfers to statement₂.

The catch body can have any number of case clauses. If none match, the exception is re-thrown.

Exceptions can carry values with them. For example, here's how to declare an exception that carries an integer:

  datatype exn { MyIntExn(int) };

Values of such exceptions must be heap-allocated. For example, you can create and throw a MyIntExn exception with

  throw new MyIntExn(42);

To catch such an exception you must use an &-pattern:

  try  statement1
  catch {
    case &MyIntExn(x):  statement2
  }

When the exception is caught, the integer value is bound to x.

The exn type is just a pre-defined @extensible datatype type. Therefore, all the standard rules for extending, creating objects, and destructing objects of a datatype apply.

How efficient is exception handling?

Entering a try block is implemented using setjmp. Throwing an exception is implemented with longjmp. Pattern-matching a datatype against each case variant in the catch clause is a pointer-comparsion. In short, exception handling is fairly lightweight.

What does let mean?

In Cyclone, let is used to declare variables. For example,

  let x,y,z;

declares the three variables x, y, and z. The types of the variables do not need to be filled in by the programmer, they are filled in by the compiler's type inference algorithm. The let declaration above is equivalent to

  _ x;
  _ y;
  _ z;

There is a second kind of let declaration, with form

  let  pattern =  expr;

It evaluates expr and matches it against pattern, initializing the pattern variables of pattern with values drawn from expr. For example,

  let x = 3;

declares a new variable x and initializes it to 3, and

  let $(y,z) = $(3,4);

declares new variables y and z, and initializes y to 3 and z to 4.

What is a pattern and how do I use it?

Cyclone's patterns are a convenient way to destructure aggregate objects, such as structs and tuples. They are also the only way to destructure datatypes. Patterns are used in Cyclone's let declarations, switch statements, and try/catch statements.

What does _ mean in a pattern?

It is a wildcard pattern, matching any value. For example, if f is a function that returns a pair, then

  let $(_,y) = f(5); 

is a way to extract the second element of the pair and bind it to a new variable y.

What does it mean when a function has an argument with type `a?

Any type that looks like ` (backquote) followed (without whitespace) by an identifier is a type variable. If a function parameter has a type variable for its type, it means the function can be called with any pointer or with an int. However, if two parameters have the same type variable, they must be instantiated with the same type. If all occurrences of `a appear directly under pointers (e.g., `a *), then an actual parameter can have any type, but the restrictions about using the same type still apply. This is called parametric polymorphism, and it's used in Cyclone as a safe alternative to casts and void *.

Do functions with type variables get duplicated like C++ template functions? Is there run-time overhead for using type variables?

No and no. Each Cyclone function gives rise to one function in the output, and types are not present at run-time. When a function is called, it does not need to know the types with which the caller is instantiating the type variables, so no instantiation actually occurs---the types are not present at run-time. We do not have to duplicate the code because we either know the size of the type or the size does not matter. This is why we don't allow type variables of memory kind as parameters---doing so would require code duplication or run-time types.

Can I use varargs?

Yes, Cyclone has a way of supporting variable-argument functions. It is not quite the same as C's, but it is safe. For instance, we have written type-safe versions of printf and scanf all within Cyclone. See the documentation on varargs for more information.

Why can't I declare types within functions?

We just haven't implemented this support yet. For now, you need to hoist type declarations and typedefs to the top-level.

What casts are allowed?

Cyclone doesn't support all of the casts that C does, because incorrect casts can lead to crashes. Instead, Cyclone supports a safe subset of C's casts. Here are some examples.

All of C's numeric casts, conversions, and promotions are unchanged.

You can always cast between type@{const-expr}, type*{const-expr}, and type?. A cast from type? to one of the other types includes a run-time check that the pointer points to a sequence of at least const-expr objects. A cast to type@{const-expr}from one of the other types includes a run-time check that the pointer is not NULL. No other casts between these type have run-time checks. A failed run-time check throws Null_Exception. A pointer into the heap can be cast to a pointer into another region. A pointer to a struct or tuple can be cast to a pointer to another struct or tuple provided the ``target type'' is narrower (it has fewer fields after ``flattening out'' nested structs and tuples) and each (flattened out) field of the target type could be the target of a cast from the corresponding field of the source type. A pointer can be cast to int. The type type*{const-expr₁}can be cast to type*{const-expr₂}provided const-expr₂ < const-expr₁, and similarly for type@{const-expr₁}and type@{const-expr₂}.

An object of type datatype T.A @ can be cast to datatype T @. The current implementation isn't quite as lenient as it should be. For example, it rejects a cast from int *{4} to $(int,int)*{2}, but this cast is safe.

For all non-pointer-containing types type, you can cast from a type ? to a char ?. This allows you to make frequent use of memcpy, memset, etc.

Why can't I implicitly fall-through to the next switch case?

We wanted to add an explicit fallthru construct in conjunction with pattern matching, and we decided to enforce use of fallthru in all cases because this is a constant source of bugs in C code.

Do I have to initialize global variables?

You currently must provide explicit initializers for global variables that may contain pointers, so that the compiler can be sure that uninitialized memory containing pointers is not read. In the future, we expect to provide some support for initializing globals in constructor functions.

Two techniques help with initializing global arrays. First, if an array element could be 0 or NULL, the compiler will insert 0 for any elements you do not specify. For example, you can write

  int x[37] = {};

to declare a global array x initialized with 37 elements, all 0. Second, you can use the comprehension form

  int x[37] = { for i < expr1 : expr2 }

provided that expr₁ and expr₂ and constant expressions. Currently, expr₂ may not use the variable i, but in the future it will be able to. Note that it is not possible to have a global variable of an abstract type because it is impossible to know any constant expression of that type.

Are there threads?

Cyclone does not yet have a threads library and some of the libraries are not re-entrant. In addition, because Cyclone uses unboxed structs of three words to represent fat pointers, and updating them is not an atomic operation, it's possible to introduce unsoundnesses by adding concurrent threads. However, in the future, we plan to provide support for threads and a static analysis for preventing these and other forms of data races.

Can I use setjmp and longjmp?

No. However, Cyclone has exceptions, which can be used for non-local control flow. The problem with setjmp and longjmp is that safety demands we prohibit a longjmp to a place no longer on the stack. A future release may have more support for non-local control flow.

What types are allowed for union members?

Currently, union members cannot contain pointers. You can have numeric types (including bit fields and enumerations), structs and tuples of allowable union-member types, and other unions.

Why can't I do anything with values of type void *?

Because we cannot know the size of an object pointed to by a pointer of type void *, we prohibit derefencing the pointer or casting it to a different pointer type. To write code that works for all pointer types, use type variables and polymorphism. Tagged unions can also substitute in some cases where void * is used in C.

What is aprintf?

The aprintf function is just like printf, but the output is placed in a new string allocated on the heap.

How do I access command-line arguments?

The type of main should be

  int main(int argc, char ?? argv);

As in C, argc is the number of command-line arguments and argv[i] is a string with the i^th argument. Unlike C, argv and each element of argv carry bounds information. Note that argc is redundant---it is always equal to numelts(argv).

Why can't I pass a stack pointer to certain functions?

If the type of a function parameter is a pointer into the heap region, it cannot be passed a stack parameter. Pointer types in typedef and struct definitions refer to the heap region unless there is an explicit region annotation.

Why do I get an incomprehensible error when I assign a local's address to a pointer variable?

If the pointer variable has a type indicating that it points into the heap, then the assignment is illegal. Try initializng the pointer variable with the local's address, rather than delaying the assignment until later.

How much pointer arithmetic can I do?

On fat pointers, you can add or subtract an int (including via increment/decrement), as in C. It is okay for the result to be outside the bounds of the object pointed to; it is a run-time error to dereference outside of the bounds. (The compiler inserts bounds information and a run-time check; an exception is thrown if the check fails.) Currently, we do not support pointer arithmetic on the other pointer types. As in C, you can subtract two pointers of the same type; the type of the result is unsigned int.

What is the type of a literal string?

The type of the string constant "foo" is char @{4} (remember the trailing null character). However, there are implicit casts from char @{4} to char @{2}, char *{4}, and char ?, so you shouldn't have to think too much about this.

Are strings NUL-terminated?

Cyclone follows C's lead on this. String literals like "foo" are NUL-terminated. Many of the library functions consider a NUL character to mark the end of a string. And library functions that return strings often ensure that they are NUL terminated. However, there is no guarantee that a string is NUL terminated. For one thing, as in C, the terminating NUL may be overwritten by any character. In C this can be exploited to cause buffer overflows. To avoid this in Cyclone, strings generally have type char ?, that is, they carry bounds information. In Cyclone a string ends when a NUL character is found, or when the bounds are exceeded.

How do I use malloc?

malloc is a Cyclone primitive, not a library function. Currently it has an extremely restricted syntax: You must write malloc(sizeof(type)). The result has type type@, so usually there is no need to explicitly cast the result (but doing so is harmless). Usually the construct new expr is more convenient than malloc followed by initialization, but malloc can be useful for certain idioms and when porting C code.

Notice that you cannot (yet) use malloc to allocate space for arrays (as in the common idiom, malloc(n*sizeof(type)). Also, the type-checker uses a conservative analysis to ensure that the fields of the allocated space are written before they are used.

Can I call free?

Yes and no. Individual memory objects may not be freed. In future versions, we may support freeing objects for which you can prove that there are no other pointers to the object. Until then, you must rely on a garbage collector to reclaim heap objects or use regions (similar to ``arenas'' or ``zones'') for managing collections of objects.

For porting code, we have defined a free function that behaves as a no-op, having type

  void free(`a::A ?);

Is there a garbage collector?

Yes, we use the Boehm-Demers-Weiser conservative collector. If you don't want to use the garbage collector (e.g., because you know that your program does little or no heap allocation), you can use the -nogc flag when linking your executable. This will make the executable smaller.

If you link against additional C code, that code must obey the usual rules for conservative garbage collection: no wild pointers and no calling malloc behind the collector's back. Instead, you should call GC_malloc. See the collector's documentation for more information.

Note that if you allocate all objects on the stack, garbage collection will never occur. If you allocate all objects on the stack or in regions, it is very unlikely collection will occur and nothing will actually get collected.

How can I make a stack-allocated array?

As in C, you declare a local variable with an array type. Also as in C, all uses of the variable, except as an argument to sizeof and &, are promoted to a pointer. If your declaration is

int x[256];

then uses of x have type int @`L{256} where L is the name of the block in which x is declared. (Most blocks are unnamed and the compiler just makes up a name.)

Stack-allocated arrays must be initialized when they are declared (unlike other local variables). Use an array-initializer, as in

  int y[] = { 0, 1, 2, 3 };
  int z[] = { for i < 256 : i };

To pass (a pointer to) the array to another function, the function must have a type indicating it can accept stack pointers, as explained elsewhere.

Can I use salloc or realloc?

Currently, we don't provide support for salloc. For realloc, we do provide support, but only on heap-allocated char ? buffers.

Why do I have to cast from * to @ if I've already tested for NULL?

Our compiler is not as smart as you are. It does not realize that you have tested for NULL, and it insists on a check (the cast) just to be sure. You can leave the cast implicit, but the compiler will emit a warning. We are currently working to incorporate a flow analysis to omit spurious warning. Because of aliasing, threads, and undefined evaluation order, a sound analysis is non-trivial.

Why can't a function parameter or struct field have type `a::M?

Type variables of memory kind can be instantiated with types of any size. There is no straightforward way to compile a function with an argument of arbitrary size. The obvious way to write such a function is to manipulate a pointer to the arbitrary size value instead. So your parameter should have type `a::M * or `a::M @.

Can I see how Cyclone compiles the code?

Just compile with flags -save-c and -pp. This tells the compiler to save the C code that it builds and passes to gcc, and print it out using the pretty-printer. You will have to work to make some sense out of the C code, though. It will likely contain many extern declarations (because the code has already gone through the preprocessor) and generated type definitions (because of tuples, tagged unions, and questionable pointers). Pattern-matching code gets translated to a mess of temporary variables and goto statements. Array-bounds checks and NULL checks can clutter array-intensive and pointer-intensive code. And all typedefs are expanded away before printing the output.

Can I use gdb on the output?

You can run gdb, but debugging support is not all the way there yet. By default, source-level debugging operations within gdb will reference the C code generated by the Cyclone compiler, not the Cyclone source itself. In this case, you need to be aware of three things. First, you have to know how Cyclone translates top-level identifiers to C identifiers (it prepends Cyc_ and separates namespaces by _ instead of ::) so you can set breakpoints at functions. Second, it can be hard to print values because many Cyclone types get translated to void *. Third, we do not yet have source correlation, so if you step through code, you're stepping through C code, not Cyclone code.

To improve this situation somehwat, you can compile your files with the option --lineno. This will insert #line directives in the generated C code that refer to the original Cyclone code. This will allow you to step through the program and view the Cyclone source rather than the generated C. However, doing this has two drawbacks. First, it may occlude some operation in the generated C code that is causing your bug. Second, compilation with --lineno is significantly slower than without. Finally, the result is not bug-free; sometimes the debugger will fall behind the actual program point and print the wrong source lines; we hope to fix this problem soon.

Two more hints: First, on some architectures, the first memory allocation appears to seg fault in GC_findlimit. This is correct and documented garbage-collector behavior (it handles the signal but gdb doesn't know that); simply continue execution. Second, a common use of gdb is to find the location of an uncaught exception. To do this, set a breakpoint at throw (a function in the Cyclone runtime).

Can I use gprof on the output?

Yes, just use the -pg flag. You should also rebuild the Cyclone libraries and the garbage collector with the -pg flag. The results of gprof make sense because a Cyclone function is compiled to a C function.

Notes for Cygwin users: First, the versions of libgmon.a we have downloaded from cygnus are wrong (every call gets counted as a self-call). We have modified libgmon.a to fix this bug, so download our version and put it in your cygwin/lib directory. Second, timing information should be ignored because gprof is only sampling 100 or 1000 times a second (because it is launching threads instead of using native Windows profiling). Neither of these problems are Cyclone-specific.

Is there an Emacs mode for Cyclone?

Sort of. In the doc/ directory of the distribution you will find a font-lock.el file and elisp code (in cyclone_dot_emacs.el) suitable for inclusion in your .emacs file. However, these files change C++ mode and use it for Cyclone rather than creating a new Cyclone mode. Of course, we intend to make our own mode rather than destroy C++-mode's ability to be good for C++. Note that we have not changed the C++ indentation rules at all; our elisp code is useful only for syntax highlighting.

Does Cyclone have something to do with runtime code generation?

Cyclone has its roots in Popcorn, a language which was safe but not as compatible with C. An offshoot of Popcorn added safe runtime code generation, and was called Cyclone. The current Cyclone language is a merger of the two, refocused on safety and C compatibility. Currently, the language does not have support for runtime code generation.

What platforms are supported?

You need a platform that has gcc, GNU make, ar, sed, either bash or ksh, and the ability to build the Boehm-Demers-Weiser garbage collector. Furthermore, the size of int and all C pointers must be the same. We actively develop Cyclone in Cygwin (a Unix emulation layer for Windows 98, NT, 2K), Linux, and Mac OS X. Versions have run on OpenBSD and FreeBSD.

Why aren't there more libraries?

We are eager to have a wider code base, but we are compiler writers with limited resources. Let us know of useful code you write.

Why doesn't List::imp_rev(l) change l to its reverse?

The library function List::imp_rev mutates its argument by reversing the tl fields. It returns a pointer to the new first cell (the old last cell), but l still points to the old first cell (the new last cell).

Can I inline functions?

Functions can be declared inline as in ISO C99. You can get additional inlining by compiling the Cyclone output with the -O2 flag. Whether a function is inlined or not has no effect on Cyclone type-checking.

If Cyclone is safe, why does my program crash?

There are certain classes of errors that Cyclone does not attempt to prevent. Two examples are stack overflow and various numeric traps, such as division-by-zero. It is also possible to run out of memory. Other crashes could be due to compiler bugs or linking against buggy C code (or linking incorrectly against C code).

Note that when using gdb, it may appear there is a seg fault in GC_findlimit(). This behavior is correct; simply continue execution.

What are compile-time constants?

Cyclone's compile-time constants are NULL, integer and character constants, and arithmetic operations over compile-time constants. Unlike C, sizeof(t) is not an integral constant expression in our current implementation of Cyclone because our compiler does not know the actual size of aggregate types; we hope to repair this in a future version. Constructs requiring compile-time constants are: tuple-subscript (e.g., x[3] for tuple x), sizes in array declarations (e.g., int y[37]), and sizes in pointer bounds (e.g., int * x{124}).

How can I get the size of an array?

If expr is an array, then numelts(expr) returns the number of elements in the array. If expr is a pointer to an array, numelts(expr) returns the number of elements in the array pointed to. If expr is a fat pointer, then the number of elements is calculated at runtime from the bounds information contained in the fat pointer. For other types, the size is determined at compile-time.

C  Libraries

C.1  C Libraries

C.2  <array.h>

void qsort(cmpfn_t<`a,`r,`r>,`a ?`r x,int len);

qsort(cmp,x,len) sorts the first len elements of array x into ascending order (according to the comparison function cmp) by the QuickSort algorithm. cmp(a,b) should return a number less than, equal to, or greater than 0 according to whether a is less than, equal to, or greater than b. qsort throws Core::InvalidArg("Array::qsort") if len is negative or specifies a segment outside the bounds of x.

qsort is not a stable sort.

void msort(cmpfn_t<`a,`H,`H>,`a ? x,int len);

msort(cmp,x,len) sorts the first len elements of array x into ascending order (according to the comparison function cmp), by the MergeSort algorithm. msort throws Core::InvalidArg("Array::msort") if len is negative or specifies a segment outside the bounds of x.

msort is a stable sort.

`a ? from_list(List::list_t<`a> l);

from_list(l) returns a heap-allocated array with the same elements as the list l.

List::list_t<`a> to_list(`a ? x);

to_list(x) returns a new heap-allocated list with the same elements as the array x.

`a ? copy(`a ? x);

copy(x) returns a fresh copy of array x, allocated on the heap.

`b ? map(`b (@ f)(`a),`a ? x);

map(f,x) applies f to each element of x, returning the results in a new heap-allocated array.

`b ? map_c(`b (@ f)(`c,`a),`c env,`a ? x);

map_c(f,env,x) is like map(f,x) except that f requires a closure env as its first argument.

void imp_map(`a (@ f)(`a),`a ? x);

imp_map(f,x) replaces each element xi of x with f(xi).

void imp_map_c(`a (@ f)(`b,`a),`b env,`a ? x);

imp_map_c is a version of imp_map where the function argument requires a closure as its first argument.

datatype exn{   Array_mismatch };

Array_mismatch is thrown when two arrays don't have the same length.

`c ? map2(`c (@ f)(`a,`b),`a ? x,`b ? y);

If x has elements x1 through xn, and y has elements y1 through yn, then map2(f,x,y) returns a new heap-allocated array with elements f(x1,y1) through f(xn,yn). If x and y don't have the same number of elements, Array_mismatch is thrown.

void app(`b (@ f)(`a),`a ?`r x);

app(f,x) applies f to each element of x, discarding the results. Note that f must not return void.

void app_c(`c (@ f)(`a,`b),`a env,`b ? x);

app_c(f,env,x) is like app(f,x), except that f requires a closure env as its first argument.

void iter(void (@ f)(`a),`a ? x);

iter(f,x) is like app(f,x), except that f returns void.

void iter_c(void (@ f)(`b,`a),`b env,`a ? x);

iter_c(f,env,x) is like app_c(f,env,x) except that f returns void.

void app2(`c (@ f)(`a,`b),`a ? x,`b ? y);

If x has elements x1 through xn, and y has elements y1 through yn, then app2(f,x,y) performs f(x1,y1) through f(xn,yn) and discards the results. If x and y don't have the same number of elements, Array_mismatch is thrown.

void app2_c(`d (@ f)(`a,`b,`c),`a env,`b ? x,`c ? y);

app2_c is a version of app where the function argument requires a closure as its first argument.

void iter2(void (@ f)(`a,`b),`a ? x,`b ? y);

iter2 is a version of app2 where the function returns void.

void iter2_c(void (@ f)(`a,`b,`c),`a env,`b ? x,`c ? y);

iter2_c is a version of app2_c where the function returns void.

`a fold_left(`a (@ f)(`a,`b),`a accum,`b ? x);

If x has elements x1 through xn, then fold_left(f,accum,x) returns f(f(...(f(x2,f(x1,accum))),xn-1),xn).

`a fold_left_c(`a (@ f)(`c,`a,`b),`c env,`a accum,`b ? x);

fold_left_c is a version of fold_left where the function argument requires a closure as its first argument.

`b fold_right(`b (@ f)(`a,`b),`a ? x,`b accum);

If x has elements x1 through xn, then fold_right(f,accum,x) returns f(x1,f(x2,...,f(xn-1,f(xn,a))...)).

`b fold_right_c(`b (@ f)(`c,`a,`b),`c env,`a ? x,`b accum);

fold_right_c is a version of fold_right where the function argument requires a closure as its first argument.

`a ? rev_copy(`a ? x);

rev_copy(x) returns a new heap-allocated array whose elements are the elements of x in reverse order.

void imp_rev(`a ? x);

imp_rev(x) reverses the elements of array x.

bool forall(bool (@ pred)(`a),`a ? x);

forall(pred,x) returns true if pred returns true when applied to every element of x, and returns false otherwise.

bool forall_c(bool (@ pred)(`a,`b),`a env,`b ? x);

forall_c is a version of forall where the predicate argument requires a closure as its first argument.

bool exists(bool (@ pred)(`a),`a ? x);

exists(pred,x) returns true if pred returns true when applied to some element of x, and returns false otherwise.

bool exists_c(bool (@ pred)(`a,`b),`a env,`b ? x);

exists_c is a version of exists where the predicate argument requires a closure as its first argument.

$(`a,`b) ? zip(`a ?`r1 x,`b ? y);

If x has elements x1 through xn, and y has elements y1 through yn, then zip(x,y) returns a new heap-allocated array with elements $(x1,y1) through $(xn,yn). If x and y don't have the same number of elements, Array_mismatch is thrown.

$(`a ?,`b ?) split($(`a,`b) ? x);

If x has elements $(a1,b1) through $(an,bn), then split(x) returns a pair of new heap-allocated arrays with elements a1 through an, and b1 through bn.

bool memq(`a ? l,`a x);

memq(l,x) returns true if x is == an element of array l, and returns false otherwise.

bool mem(int (@ cmp)(`a,`a),`a ? l,`a x);

mem(cmp,l,x) is like memq(l,x) except that the comparison function cmp is used to determine if x is an element of l. cmp(a,b) should return 0 if a is equal to b, and return a non-zero number otherwise.

`a ? extract(`a ? x,int start,int * len_opt);

extract(x,start,len_opt) returns a new array whose elements are the elements of x beginning at index start, and continuing to the end of x if len_opt is NULL; if len_opt points to an integer n, then n elements are extracted. If n<0 or there are less than n elements in x starting at start, then Core::InvalidArg("Array::extract") is thrown.

C.3  <bitvec.h>

typedef int ?`r bitvec_t<`r>;

bitvec_t is the type of bit vectors.

bitvec_t new_empty(int);

new_empty(n) returns a bit vector containing n bits, all set to 0.

bitvec_t new_full(int);

new_full(n) returns a bit vector containing n bits, all set to 1.

bitvec_t new_copy(bitvec_t);

new_copy(v) returns a copy of bit vector v.

bool get(bitvec_t,int);

get(v,n) returns the nth bit of v.

void set(bitvec_t,int);

set(v,n) sets the nth bit of v to 1.

void clear(bitvec_t,int);

clear(v,n) sets the nth bit of v to 0.

bool get_and_set(bitvec_t,int);

get_and_set(v,n) sets the nth bit of v to 1, and returns its value before the set.

void clear_all(bitvec_t);

clear_all(v) sets every bit in v to 0.

void set_all(bitvec_t);

set_all(v) sets every bit in v to 1.

bool all_set(bitvec_t bvec,int sz);

all_set(v) returns true if every bit in v is set to 1, and returns false otherwise.

void union_two(bitvec_t dest,bitvec_t src1,bitvec_t src2);

union_two(dest,src1,src2) sets dest to be the union of src1 and src2: a bit of dest is 1 if either of the corresponding bits of src1 or src2 is 1, and is 0 otherwise.

void intersect_two(bitvec_t dest,bitvec_t src1,bitvec_t src2);

intersect_two(dest,src1,src2) sets dest to be the intersection of src1 and src2: a bit of dest is 1 if both of the corresponding bits of src1 and src2 are 1, and is 0 otherwise.

void diff_two(bitvec_t dest,bitvec_t src1,bitvec_t src2);

diff_two(dest,src1,src2) sets dest to be the difference of src1 and src2: a bit of dest is 1 if the corresponding bit of src1 is 1, and the corresponding bit of src2 is 0; and is 0 otherwise.

bool compare_two(bitvec_t src1,bitvec_t src2);

compare_two(src1,src2) returns true if src1 and src2 are equal, and returns false otherwise.

C.4  <buffer.h>

typedef struct t @ T;

T is the type of buffers.

T create(unsigned int n);

create(n) returns a fresh buffer, initially empty. n is the initial size of an internal character array that holds the buffer's contents. The internal array grows when more than n character have been stored in the buffer; it shrinks back to the initial size when reset is called. If n is negative, no exception is thrown; a buffer with a small amount of internal storage is returned instead.

mstring_t contents(T);

contents(b) heap allocates and returns a string whose contents are the contents of buffer b.

size_t length(T);

length(b) returns the number of characters in buffer b.

void clear(T);

clear(b) makes b have zero characters. Internal storage is not released.

void reset(T);

reset(b) sets the number of characters in b to zero, and sets the internal storage to the initial string. This means that any storage used to grow the buffer since the last create or reset can be reclaimed by the garbage collector.

void add_char(T,char);

add_char(b,c) appends character c to the end of b.

void add_substring(T,string_t,int offset,int len);

add_substring(b,s,ofs,len) takes len characters starting at offset ofs in string s and appends them to the end of b. If ofs and len do not specify a valid substring of s, then the function throws InvalidArg("Buffer::add_substring"). Note, the substring specified by offset and len may contain NUL (0) characters; in any case, the entire substring is appended to b, not just the substring up to the first NUL character.

void add_string(T,string_t);

add_string(b,s) appends the string s to the end of b.

void add_buffer(T buf_dest,T buf_source);

add_buffer(b1,b2) appends the current contents of b2 to the end of b1. b2 is not modified.

C.5  <core.h>

typedef const char ?@nozeroterm`r string_t<`r>;

A string_t<`r> is a constant array of characters allocated in region `r.

typedef char ?@nozeroterm`r mstring_t<`r>;

An mstring_t<`r> is a non-const (mutable) array of characters allocated in region `r.

typedef string_t<`r1> @`r2 stringptr_t<`r1,`r2>;

A stringptr_t<`r1,`r2> is used when a ``boxed'' string is needed, for example, you can have a list of string pointers, but not a list of strings.

typedef mstring_t<`r1> @`r2 mstringptr_t<`r1,`r2>;

mstringptr_t is the mutable version of stringptr_t.

typedef char *@nozeroterm`r Cbuffer_t<`r>;

Cbuffer_t is a possibly-NULL, non-zero-terminated C buffer

typedef char @@nozeroterm`r CbufferNN_t<`r>;

CbufferNN_t is a non-NULL, non-zero-terminated C buffer

typedef const char ?@nozeroterm`r buffer_t<`r>;

buffer_t is a non-zero-terminated dynamically sized buffer

typedef int bool;

In Cyclone, we use bool as a synonym for int. We also define macros true and false, which are 1 and 0, respectively.

typedef tag_t<valueof_t(sizeof(`a))> sizeof_t<`a>;

sizeof_typ<T> is the singleton type of sizeof(T).

struct Opt<`a>{   `a v; };

A struct Opt is a cell with a single field, v (for value).

typedef struct Opt<`a> *`r opt_t<`a,`r>;

An opt_t is a pointer to a struct Opt. An opt_t can be used to pass an optional value to a function, or return an optional result. For example, to return no result, return NULL; to return a result x, return new Opt(x).

Another way to return an option result of type t would be to return a pointer to t. The opt_t type is useful primarily when porting Objective Caml code, which has a corresponding type.

opt_t<`b,`H> opt_map(`b (@ f)(`a),opt_t<`a,`r> x);

opt_map(f,x) applies f to the value contained in option x, if any, and returns the result as an option; if x is NULL, opt_map(f,x) returns NULL.

mstring_t<`H> new_string(unsigned int);

new_string(n) allocates space for n characters on the heap and returns a pointer to the space. All of the characters are set to NUL (0).

mstring_t<`r> rnew_string(region_t<`r>,unsigned int);

rnew_string(r,n) allocates space for n characters in the region with handle r, and returns a pointer to the space. All of the characters are set to NUL (0).

bool true_f(`a);

true_f is the constant true function: true_f(x) returns true regardless of the value of x.

bool false_f(`a);

false_f is the constant false function.

`a fst($(`a,`b) @);

fst(x) returns the first element of the pair pointed to by x.

`b snd($(`a,`b) @);

snd(x) returns the second element of the pair pointed to by x.

`c third($(`a,`b,`c) @);

third(x) returns the third element of the triple pointed to by x.

`a identity(`a);

identity is the identity function: identity(x) returns x.

int intcmp(int,int);

intcmp is a comparison function on integers: intcmp(i1,i2) returns a number less than, equal to, or greater than 0 according to whether i1 is less than, equal to, or greater than i2.

int charcmp(char,char);

charcmp is a comparison function on char.

int ptrcmp(`a @`r,`a @`r);

ptrcmp is a comparison function on pointers.

int nptrcmp(`a *`r,`a *`r);

nptrcmp is a comparison function on nullable pointers.

datatype exn{   Invalid_argument(string_t) };

Invalid_argument is an exception thrown by library functions when one of their arguments is inappropriate.

datatype exn{   Failure(string_t) };

Failure is an exception that's thrown by library functions when they encounter an unexpected error.

datatype exn{   Impossible(string_t) };

The Impossible exception is thrown when a supposedly impossible situation occurs (whether in a library or in your own code). For example, you might throw Impossible if an assertion fails.

datatype exn{   Not_found };

The Not_found exception is thrown by search functions to indicate failure. For example, a function that looks up an entry in a table can throw Not_found if the entry is not found.

region_t<`H> heap_region;

heap_region is the region handle of the heap.

region_t<`U> unique_region;

unique_region is the region handle of the unique pointer region.

void ufree(`a ?`U ptr) __attribute__((noliveunique(1)));

ufree frees a unique pointer.

region_t<`RC> refcnt_region;

refcnt_region is the region handle of the reference-counted region. Data allocated in this region contains an additional reference count for managing aliases.

int refptr_count(`a ?`RC ptr) __attribute__((noconsume(1)));

refptr_count(p) returns the current reference count for p (always >= 1); p is not consumed.

`a ?`RC alias_refptr(`a ?`RC ptr) __attribute__((noconsume(1)));

alias_refptr(p) returns an alias to p, and increments the reference count by 1. p is not consumed.

void drop_refptr(`a ?`RC ptr) __attribute__((noliveunique(1)));

drop_refptr(p) decrements the reference count on p by 1. If the reference count goes to 0, it frees p. This will not recursively decrement reference counts to embedded pointers, meaning that those pointers will have to get GC'ed if p ends up being freed.

struct DynamicRegion<`r::R>;

struct DynamicRegion<`r> is an abstract type for the dynamic region named `r. Dynamic regions can be created and destroyed at will, but access to them must be done through the open_region function.

typedef struct DynamicRegion<`r1> @`r2 region_key_t<`r1,                                                     `r2>;

A region_key_t<`r1,`r2> is a pointer (in `r2) to a DynamicRegion<`r1>. Keys are used as capabilities for accessing a dynamic region. You have to present a key to the open procedure to access the region.

typedef region_key_t<`r,`U> uregion_key_t<`r>;

A uregion_key_t<`r> is a unique pointer to a DynamicRegion<`r>. You can't make copies of the key, but if you call free_ukey, then you are assured that the region `r is reclaimed.

typedef region_key_t<`r,`RC> rcregion_key_t<`r>;

A rcregion_key_t<`r> is a reference-counted pointer to a DynamicRegion<`r>. You can make copies of the key using alias_refptr which increments the reference count. You can call free_rckey to destroy the key, which will decrement the reference count. If the count reaches zero, then the region will be reclaimed.

struct NewDynamicRegion<`r2>{<`r>   region_key_t<`r,`r2> key; };

A struct NewDynamicRegion<`r2> is used to return a new dynamic region `r. The struct hides the name of the region and must be opened, guaranteeing that the type-level name is unique.

struct NewDynamicRegion<`U> new_ukey();

new_ukey() creates a fresh dynamic region `r and returns a unique key for that region.

struct NewDynamicRegion<`RC> new_rckey();

new_rckey() creates a fresh dynamic region `r and returns a reference-counted key for that region.

void free_ukey(uregion_key_t<`r> k);

free_ukey(k) takes a unique key for the region `r and deallocates the region `r and destroys the key k.

void free_rckey(rcregion_key_t<`r> k);

free_rckey(k) takes a reference-counted key for the region `r, decrements the reference count and destroyes the key k. If the reference count becomes zero, then all keys have been destroyed and the region `r is deallocated.

`result open_region(region_key_t<`r,`r2> key,`arg arg,                     `result (@ body)(region_t<`r> h,                                      `arg arg)) __attribute__((noconsume(1)));

open_region(k,arg,body) extracts a region handle h for the region `r which the k provides access to. The handle and value arg are passed to the function pointer body and the result is returned. Note that k can be either a uregion_key_t or an rcregion_key_t. The caller does not need to have static access to region `r when calling open_region but that capability is allowed within body. In essence, the key k provides dynamic evidence that `r is still live.

`a ?`r mkfat(`a @{valueof(`n)}`r arr,Core::sizeof_t<`a> s,              tag_t<`n> n);

mkfat can be used to convert a thin pointer (@) of elements of type `a to a fat pointer (?). It requires that you pass in the size of the element type, as well as the number of elements.

void rethrow(datatype exn @) __attribute__((noreturn));

throws the exception without updating the source or line number information. Useful for try ... catch case e: ... rethrow(e);

const char * get_exn_name(datatype exn @);

returns the name of the exception as a string

const char * get_exn_filename();

if an exception is thrown, then you can use @get_exn_filename@ to determine what source file caused the exception.

int get_exn_lineno();

if an exception is thrown, then you can use @get_exn_lineno@ to determine what source line caused the exception.

unsigned int arr_prevsize(`a ?,sizeof_t<`a>);

arr_prevsize(p,sz) returns the buffer space available preceding the pointer p in the dynamic array p points into. sz is the size of the elements in the array returned by sizeof.

C.6  <dict.h>

typedef struct Dict<`a,`b,`r> dict_t<`a,`b,`r>;

A value of type dict_t<`a,`b,`r> is a dictionary that maps keys of type `a to values of type `b; the dictionary datatypes live in region `r.

datatype exn{   Present };

Present is thrown when a key is present but not expected.

datatype exn{   Absent };

Absent is thrown when a key is absent but should be present.

dict_t<`a,`b> empty(int (@ cmp)(`a,`a));

empty(cmp) returns an empty dictionary, allocated on the heap. cmp should be a comparison function on keys: cmp(k1,k2) should return a number less than, equal to, or greater than 0 according to whether k1 is less than, equal to, or greater than k2 in the ordering on keys.

dict_t<`a,`b,`r> rempty(region_t<`r>,int (@ cmp)(`a,                                                  `a));

rempty(r,cmp) is like empty(cmp) except that the dictionary is allocated in the region with handle r.

dict_t<`a,`b,`r> rshare(region_t<`r>,dict_t<`a,`b,`r2>:{`r2} > `r);

rshare(r,d) creates a virtual copy in region `r of the dictionary d that lives in region `r2. The internal data structures of the new dictionary share with the old one.

bool is_empty(dict_t d);

is_empty(d) returns true if d is empty, and returns false otherwise.

int cardinality(dict_t d);

cardinality(d) returns the number of keys in the dictionary.

bool member(dict_t<`a> d,`a k);

member(d,k) returns true if k is mapped to some value in d, and returns false otherwise.

dict_t<`a,`b,`r> insert(dict_t<`a,`b,`r> d,`a k,`b v);

insert(d,k,v) returns a dictionary with the same mappings as d, except that k is mapped to v. The dictionary d is not modified.

dict_t<`a,`b,`r> insert_new(dict_t<`a,`b,`r> d,`a k,                             `b v);

insert_new(d,k,v) is like insert(d,k,v), except that it throws Present if k is already mapped to some value in d.

dict_t<`a,`b,`r> inserts(dict_t<`a,`b,`r> d,list_t<$(`a,                                                      `b) @> l);

inserts(d,l) inserts each key, value pair into d, returning the resulting dictionary.

dict_t<`a,`b> singleton(int (@ cmp)(`a,`a),`a k,`b v);

singleton(cmp,k,v) returns a new heap-allocated dictionary with a single mapping, from k to v.

dict_t<`a,`b,`r> rsingleton(region_t<`r>,int (@ cmp)(`a,                                                      `a),                             `a k,`b v);

rsingleton(r,cmp,k,v) is like singleton(cmp,k,v), except the resulting dictionary is allocated in the region with handle r.

`b lookup(dict_t<`a,`b> d,`a k);

lookup(d,k) returns a pointer to the value associated with key k in d, or throws Absent if k is not mapped to any value.

`b lookup_other(dict_t<`a,`b,`r> d,int (@ cmp)(`c,`a),                 `c k);

lookup_other(d,cmp,k) returns a pointer to the value associated with key k in d, or throws Absent if k is not mapped to any value. The comparison function associated with the dictionary is ignored and instead, the cmp argument is used. Note that cmp must respect the same ordering constraints as the dictionary's built-in comparison in order to succeed. This is useful when the dictionary has keys that are pointers into one region, but you want to look up with a key that is a pointer into another region.

`b *`r lookup_opt(dict_t<`a,`b,`r> d,`a k);

lookup_opt(d,k) returns NULL if k is not mapped to any value in d, and returns a non-NULL, heap-allocated option containing the value k is mapped to in d otherwise.

bool lookup_bool(dict_t<`a,`b> d,`a k,`b @ ans);

If d maps k to a value, then lookup_bool(d,k,ans) assigns that value to *ans and returns true; otherwise, it returns false.

`c fold(`c (@ f)(`a,`b,`c),dict_t<`a,`b> d,`c accum);

If d has keys k1 through kn mapping to values v1 through vn, then fold(f,d,accum) returns f(k1,v1,...f(kn,vn,accum)...).

`c fold_c(`c (@ f)(`d,`a,`b,`c),`d env,dict_t<`a,`b> d,           `c accum);

fold_c(f,env,d,accum) is like fold(f,d,accum) except that f takes closure env as its first argument.

void app(`c (@ f)(`a,`b),dict_t<`a,`b> d);

app(f,d) applies f to every key/value pair in d; the results of the applications are discarded. Note that f cannot return void.

void app_c(`c (@ f)(`d,`a,`b),`d env,dict_t<`a,`b> d);

app_c(f,env,d) is like app(f,d) except that f takes closure env as its first argument.

void iter(void (@ f)(`a,`b),dict_t<`a,`b> d);

iter(f,d) is like app(f,d) except that f returns void.

void iter_c(void (@ f)(`c,`a,`b),`c env,dict_t<`a,`b> d);

iter_c(f,env,d) is like app_c(f,env,d) except that f returns void.

void iter2(void (@ f)(`b,`b),dict_t<`a,`b> d1,dict_t<`a,                                                      `b> d2);

For every key k in the domain of both d1 and d2, iter2(f,d1,d2) performs f(lookup(d1,k), lookup(d2,k)). If there is any key present in d1 but not d2, then Absent is thrown.

void iter2_c(void (@ f)(`c,`b,`b),`c env,dict_t<`a,                                                 `b> d1,              dict_t<`a,`b> d2);

iter2_c is like iter except that f takes a closure as its first argument.

`c fold2_c(`c (@ f)(`d,`a,`b1,`b2,`c),`d env,dict_t<`a,                                                     `b1> d1,            dict_t<`a,`b2> d2,`c accum);

If k1 through kn are the keys of d1, then fold2_c(f,env,d1,d2,accum) returns f(env,k1,lookup(k1,d1),lookup(k1,d2), ... f(env,kn,lookup(kn,d1),lookup(kn,d2),accum)...). If there is any key present in d1 but not d2, then Absent is thrown.

dict_t<`a,`b,`r> rcopy(region_t<`r>,dict_t<`a,`b>);

rcopy(r,d) returns a copy of d, newly allocated in the region with handle r.

dict_t<`a,`b> copy(dict_t<`a,`b>);

copy(r,d) returns a copy of d, newly allocated on the heap.

dict_t<`a,`c> map(`c (@ f)(`b),dict_t<`a,`b> d);

map(f,d) applies f to each value in d, and returns a new dictionary with the results as values: for every binding of a key k to a value v in d, the result binds k to f(v). The returned dictionary is allocated on the heap.

dict_t<`a,`c,`r> rmap(region_t<`r>,`c (@ f)(`b),dict_t<`a,                                                        `b> d);

rmap(r,f,d) is like map(f,d), except the resulting dictionary is allocated in the region with handle r.

dict_t<`a,`c> map_c(`c (@ f)(`d,`b),`d env,dict_t<`a,                                                   `b> d);

map_c(f,env,d) is like map(f,d) except that f takes env as its first argument.

dict_t<`a,`c,`r> rmap_c(region_t<`r>,`c (@ f)(`d,`b),                         `d env,dict_t<`a,`b> d);

rmap_c(r,f,env,d) is like map_c(f,env,d) except that the resulting dictionary is allocated in the region with handle r.

dict_t<`a,`b,`r> union_two_c(`b (@ f)(`c,`a,`b,`b),                              `c env,dict_t<`a,`b,`r> d1,                              dict_t<`a,`b,`r> d2);

union_two_c(f,env,d1,d2) returns a new dictionary with a binding for every key in d1 or d2. If a key appears in both d1 and d2, its value in the result is obtained by applying f to the two values, the key, and env. Note that the resulting dictionary is allocated in the same region as d2. (We don't use union as the name of the function, because union is a keyword in Cyclone.)

dict_t<`a,`b,`r> intersect(`b (@ f)(`a,`b,`b),dict_t<`a,                                                      `b,                                                      `r> d1,                            dict_t<`a,`b,`r> d2);

intersect(f,d1,d2) returns a new dictionary with a binding for every key in both d1 and d2. For every key appearing in both d1 and d2, its value in the result is obtained by applying f to the key and the two values. Note that the input dictionaries and result must be allocated in the same region.

dict_t<`a,`b,`r> intersect_c(`b (@ f)(`c,`a,`b,`b),                              `c env,dict_t<`a,`b,`r> d1,                              dict_t<`a,`b,`r> d2);

intersect_c(f,env,d1,d2) is like intersect(f,d1,d2), except that f takes env as its first argument.

bool forall_c(bool (@ f)(`c,`a,`b),`c env,dict_t<`a,                                                  `b> d);

forall_c(f,env,d) returns true if f(env,k,v) returns true for every key k and associated value v in d, and returns false otherwise.

bool forall_intersect(bool (@ f)(`a,`b,`b),dict_t<`a,                                                   `b> d1,                       dict_t<`a,`b> d2);

forall_intersect(f,d1,d2) returns true if f(k,v1,v2) returns true for every key k appearing in both d1 and d2, where v1 is the value of k in d1, and v2 is the value of k in d2; and it returns false otherwise.

$(`a,`b) @`r rchoose(region_t<`r>,dict_t<`a,`b> d);

rchoose(r,d) returns a key/value pair from d, allocating the pair in region r; if d is empty, Absent is thrown.

list_t<$(`a,`b) @> to_list(dict_t<`a,`b> d);

to_list(d) returns a list of the key/value pairs in d, allocated on the heap.

list_t<$(`a,`b) @`r,`r> rto_list(region_t<`r>,dict_t<`a,                                                      `b> d);

rto_list(r,d) is like to_list(d), except that the resulting list is allocated in the region with handle r.

dict_t<`a,`b> filter(bool (@ f)(`a,`b),dict_t<`a,`b> d);

filter(f,d) returns a dictionary that has a binding of k to v for every binding of k to v in d such that f(k,v) returns true. The resulting dictionary is allocated on the heap.

dict_t<`a,`b,`r> rfilter(region_t<`r>,bool (@ f)(`a,                                                  `b),                          dict_t<`a,`b> d);

rfilter(r,f,d) is like filter(f,d), except that the resulting dictionary is allocated in the region with handle r.

dict_t<`a,`b> filter_c(bool (@ f)(`c,`a,`b),`c env,                        dict_t<`a,`b> d);

filter_c(f,env,d) is like filter(f,d) except that f takes a closure env as its first argument.

dict_t<`a,`b,`r> rfilter_c(region_t<`r>,bool (@ f)(`c,                                                    `a,                                                    `b),                            `c env,dict_t<`a,`b> d);

rfilter_c(r,f,env,d) is like filter_c(f,env,d), except that the resulting dictionary is allocated in the region with handle r.

dict_t<`a,`b> difference(dict_t<`a,`b> d1,dict_t<`a,                                                  `b> d2);

difference(d1,d2) returns a dictionary that has a binding of k to v for every binding of k to v in d1 where k is not in d2. (Note that the values of d2 are not relevant to difference(d1,d2).) The resulting dictionary is allocated on the heap.

dict_t<`a,`b,`r> rdifference(region_t<`r>,dict_t<`a,                                                  `b> d1,                              dict_t<`a,`b> d2);

rdifference(d1,d2) is like difference(d1,d2), except that the resulting dictionary is allocated in the region with handle r.

dict_t<`a,`b> delete(dict_t<`a,`b>,`a);

delete(d,k) returns a dictionary with the same bindings as d, except that any binding of k is removed. The resulting dictionary is allocated on the heap.

dict_t<`a,`b,`r> rdelete(region_t<`r>,dict_t<`a,`b>,                          `a);

rdelete(r,d,k) is like delete(d,k) except that the result is allocated in the region with handle r.

dict_t<`a,`b,`r> rdelete_same(dict_t<`a,`b,`r>,`a);

rdelete_same(d,k) is like delete(d,k), except that the resulting dictionary is allocated in the same region as the input dictionary d. This can be faster than delete(d,k) because it avoids a copy when k is not a member of d.

Iter::iter_t<$(`a,`b),`bd> make_iter(region_t<`r1> rgn,                                      dict_t<`a,`b,`r2> d:regions($(`a,                                                                    `b)) > `bd,                                                          {`r1,                                                           `r2} > `bd);

make_iter(s) returns an iterator over the set s; O(log n) space is allocated in rgn where n is the number of elements in d

C.7  <filename.h>

mstring_t concat(string_t,string_t);

Assuming that s1 is a directory name and s2 is a file name, concat(s1,s2) returns a new (heap-allocated) file name for the child s2 of directory s1.

mstring_t chop_extension(string_t);

chop_extension(s) returns a copy of s with any file extension removed. A file extension is a period (`.') followed by a sequence of non-period characters. If s does not have a file extension, chop_extension(s) throws Core::Invalid_argument("chop_extension").

mstring_t dirname(string_t);

dirname(s) returns the directory part of s. For example, if s is "foo/bar/baz", dirname(s) returns "foo/bar".

mstring_t basename(string_t);

basename(s) returns the file part of s. For example, if s is "foo/bar/baz", basename(s) returns "baz".

bool check_suffix(string_t,string_t);

check_suffix(filename,suffix) returns true if filename ends in suffix, and returns false otherwise.

mstring_t gnuify(string_t);

gnuify(s) forces s to follow Unix file name conventions: any Windows separator characters (backslashes) are converted to Unix separator characters (forward slashes).

C.8  <fn.h>

typedef struct Function<`arg,`res,`bd> @ fn_t<`arg,                                               `res,                                               `bd>;

A value of type fn_t<`arg,`res,`eff> is a function and its closure; `arg is the argument type of the function, `res is the result type, and `bd is a region that regions(`arg) outlive.

fn_t<`arg,`res,`bd> make_fn(`res (@`bd f)(`env,`arg),                             `env x:regions(`env) > `bd);

make_fn(f,env) builds a closure out of a function and an environment.

fn_t<`arg,`res,`bd> fp2fn(`res (@`bd f)(`arg):regions($(`arg,                                                         `res)) > `bd);

fp2fn(f) converts a function pointer to a closure.

`res apply(fn_t<`arg,`res> f,`arg x);

apply(f,x) applies closure f to argument x (taking care of the hidden environment in the process).

fn_t<`a,`c,`bd> compose(fn_t<`a,`b,`bd> g,fn_t<`b,`c,                                                `bd> f:regions($(`a,                                                                 `b,                                                                 `c)) > `bd);

compose(g,f) returns the composition of closures f and g; apply(compose(g,f),x) has the same effect as apply(f,apply(g,x)).

fn_t<`a,fn_t<`b,`c,`bd>,`bd> curry(fn_t<$(`a,`b) @,                                         `c,`bd> f:regions($(`a,                                                             `b,                                                             `c)) > `bd);

curry(f) curries a closure that takes a pair as argument: if x points to a pair $(x1,x2), then apply(f,x) has the same effect as apply(apply(curry(f),x1),x2).

fn_t<$(`a,`b) @,`c,`bd> uncurry(fn_t<`a,fn_t<`b,`c,                                              `bd>,`bd> f:regions($(`a,                                                                    `b,                                                                    `c)) > `bd);

uncurry(f) converts a closure that takes two arguments in sequence into a closure that takes the two arguments as a pair: if x points to a pair $(x1,x2), then apply(uncurry(f),x) has the same effect as apply(apply(f,x1),x2).

List::list_t<`b> map_fn(fn_t<`a,`b> f,List::list_t<`a> x);

map_fn(f,x) maps the closure f on the list x: if x has elements x1 through xn, then map_fn(f,x) returns a new heap-allocated list with elements apply(f,x1) through apply(f,xn).

C.9  <hashtable.h>

typedef struct Table<`a,`b,`r> @`r table_t<`a,`b,`r>;

A table_t<`a,`b> is a hash table with keys of type `a and values of type `b.

table_t<`a,`b> create(int sz,int (@ cmp)(`a,`a),int (@ hash)(`a));

create(sz,cmp,hash) returns a new hash table that starts out with sz buckets. cmp should be a comparison function on keys: cmp(k1,k2) should return a number less than, equal to, or greater than 0 according to whether k1 is less than, equal to, or greater than k2. hash should be a hash function on keys. cmp and hash should satisfy the following property: if cmp(k1,k2) is 0, then hash(k1) must equal hash(k2).

table_t<`a,`b,`r> rcreate(region_t<`r> r,int sz,int (@ cmp)(`a,                                                             `a),                           int (@ hash)(`a));

rcreate(r,sz,cmp,hash) is similar to create but allocates its result in the region r instead of the heap.