.NET, Webservers, Nemerle, and macros

I've recently been trying to make myself and my skills more "marketable", so I launched a three-pronged offensive:

1. to start an opensource project and get it on github,
2. to get better understanding of networking protocols in general, and HTTP in particular,
3. to deepen my understanding of the .NET (and Mono) platforms.

The result of this so far is my most recent project, httplib¹, which is a webserver library, built on top of the System.Net.HttpListener class. The github also contains a couple of executables built against the library—a server for general testing and development of ideas, and a server for what I hope will be a modern forum application.

While C# is the obvious choice of language for this kind of project, I actually decided to go with Nemerle instead—.NET being what it is, we still have access to any existing C# tools and libraries, we just need to 'translate' C# examples into Nemerle when reading the docs (which is actually pretty easy to do, given the comparison between the two on the Nemerle github wiki). The main reasons for choosing Nemerle are that it has a very strong influence from functional programming languages such as Standard ML and Scheme, while maintaining a somewhat familiar "C-family" syntax. But the primary attraction of Nemerle for me is its macro capabilities which I want to expand on a little more in this post.

Unlike C/C++, Nemerle's if statement actually functions as an expression, which means that code like the following is perfectly legitimate:

def value = if(condition) { 1 } else { 2 };

(As an aside, the else clause is mandatory—its omission causes a syntax error. The when keyword exists for conditional execution of code. See here for further discussion of this.)

Coming as I do from a C++ background, I found myself wanting to write the above code more succinctly, as follows:

def value = condition ? 1 : 2;

It turns out that the ternary operator isn't natively supported in Nemerle, but we can build one easily enough using a macro. We can actually make this macro as simple or as complex as we like, depending on the quality of our implementation. But, as Nemerle fully supports type inference (omitting manifest type information from the source code which the compiler can infer), we ultimately want to author a macro which supports it too.

The basic macro definition is a binary operator for ?, the outline of which is as follows:

macro @?(condition, predicate) {
    def type_builder = Macros.ImplicitCTX();

    def expansion(condition, predicate, last_try) {

        def texpr = type_builder.TypeExpr(condition);

        /* ...expansion code here... */
    }

    def result = expansion(condition, predicate, false);

    match(result) {
        | Some(r) => r
        | None() => {
            type_builder.DelayMacro( last_try => {
                expansion(condition, predicate, last_try)
            })
        }
    }
}

(The type_builder object is our interface to the Nemerle compiler at compile time: for the purposes of this post, we can use it to get type information for expressions we are evaluating, and to ask for the macro expansion to be postponed if the type information hasn't yet been inferred.)

The main body of the macro is defined in a local function expansion() which takes the arguments to the macro (condition and predicate) and a flag last_try which will be explained shortly. expansion() returns either Some(expression) or None() (the full return type is Nemerle.Core.option[Nemerle.Compiler.Parsetree.PExpr]—either a valid piece of AST, or nothing). In the case that we return some expression, we can simply use that expression as the macro's result; if None() is returned, the type_builder doesn't have enough type information at the time of macro expansion: we need to call the method type_builder.DelayMacro(), which is expecting a lambda expression of type bool -> option[PExpr]. In this case, we want to call our expansion() function again, and let the typer provide the last_try variable. (If last_try is true and we still haven't been able to expand the macro satisfactorily, then we will give up and call Message.Error() from within expansion(), causing a compile error.)

This basic outline should work for any Nemerle macro where delayed typing is needed—so we can now think about the contents of the expansion() function at the point marked /* ...expansion code here... */. The two arguments, condition and predicate represent the AST expressions on the left-hand and right-hand sides of the ? operator in the source code. We need to validate these expressions and emit our own AST as a result, or we need to cause a compile error if our validation fails.

Nemerle allows Scheme-like quasiquotation, to match and build syntax. The final result of our macro in the successful case will be this (as we'd expect, it's simply an if/else expression wrapped in a Some() constructor):

Some(<[ if($c) { $pass } else { $fail }; ]>)

The bracket markers <[ and ]> delineate the quasiquotation. Within it, $name allow us to insert (or 'splice') the contents of a variable. In the expression above, the variable c contains the result of matching condition, and pass and fail are derived from predicate. Without going into painstaking detail here, c is either simply condition itself if it's a bool expression, otherwise it is set to <[ $condition != null ]>. This allows us to write expressions such as the following (where o is an object reference), allowing use to omit the != null which would otherwise be required:

def result = o ? o.callMethod(): default_value;

This refinement is evoking the C++ idiom for testing the value of a pointer in a boolean context:

auto result = p ? p->callMethod(): default_value;

With regard to the predicate argument, we match it against <[ $pass : $fail ]>, which indicates we are expecting two expressions separated by a :, so we aren't building a true ternary operator; just a binary ? one which expects to find a : on its right-hand side. This isn't perfect (it doesn't handle nested ternaries as well as could be desired), but is probably as close as we can get without compromising our desired syntax, and we can always use parentheses to disambiguate if necessary, for example:

a ? (b ? 1 : 2) : (b ? 3 : 4);

(We can always argue that nested ternary operators is poor style, and should be discouraged anyway.)

The full source code is in my httplib project on github— it should be pretty straightforward to take this file and incorporate it into another codebase as-is, or with modifications for namespace. Some basic NUnit tests are also available here. (This code is under a 3-clause BSD license). One thing to bear in mind is that Nemerle macros need to be compiled into their own DLL, which the compiler references (e.g. something like ncc -r macros.dll -o out.exe source.n). For anyone seriously interested in Nemerle, there's a wealth of information on their github wiki, which provided all the information I needed to build this macro—the pages under "Macros extended course (Parts 1-4)" in particular go into a lot of detail on how macros work.

---

1 Again, I should draw attention to how bad I am at choosing names for projects.^↩

Playing with Rust I—Towers of Hanoi

I've been hearing about Rust recently, a programming language which compiles to native code with an emphasis on memory safety. As the 1.0.0-alpha version was recently announced, I downloaded it from here and decided to write a couple of quick console applications to get a feel for the language.

First up, a Tower of Hanoi solver. As you can see, Rust has a something of a C++ 'look and feel', using several of the same keywords (const, struct, for, while) and use of {} braces to indicate code blocks and <> angle brackets for type variations (called 'generics' in Rust parlance vs. C++ templates).

There are some new keywords as well: let, fn, impl, mut, match among others. For most of these, the intended meanings are reasonably clear (fn is short for 'function', mut is short for 'mutable'; Rust tends towards extremely terse terminology).

I don't want to get into a detail-by-detail exposition of every aspect of the Rust syntax—I'm hoping that the general form of the code should be fairly clear to C++ readers, at least. I will touch on a few things though:

• struct is used to define a type's data members, impl is used to add methods to an existing type. Per-object methods can take either &self or &mut self, methods which don't have a self parameter are static. It is conventional to define a static new() method for each type which can be used to create new instances of that type. This listing attempts to follow that convention.
• This listing is currently hardcoded to solve the case of 5 pegs on 3 poles. The initial state of the Scene is hardcoded in Scene::new() (create the poles, place pegs on the first pole), and the HanoiSolver is initialized to operate on that state. It would probably not be too hard to fix the code to allow general solutions of m pegs on n poles.
• Scene is responsible for drawing the current state of the simulation onto the TTY (from its show() method, using the println!() macro). move_peg() attempts a valid move of a peg from one pole to another, returning true if it can, or false if it can't. (The solver only attempts valid moves if it is set up correctly so this should be a non-issue, but it could be extended to support e.g. a human player.)
• I quite like the impl Iterator for HanoiSolver {} syntax for implementing traits, that seems nice. The HanoiSolver just builds all the states it wants to visit in its new() function and stores them in a Vec of (from, to) move co-ordinates, which makes the implementation of next() extremely simple.
One particularly interesting piece of syntax to note is the presence or absence of a ; at the end of a {} block. If the ; is present, the block has no return value (to be precise, it returns ()). But if it's absent, then the final expression of the block becomes the return value. This might sound confusing, but I actually found it to be fairly intuitive, and I tried to make use of this idiom when I felt it was appropriate. You can of course use return to return a value from a block at any point.
• The match construct is pretty powerful, similar to something you'd see in a functional language Haskell or Standard ML. You can think of it as a superpowered version of a switch statement. The syntax if let/while let is somewhat related to match—it attempts to bind structured variables to an expression, and conditionally executes some code if the binding succeeds. Rust's type system is quite rich, it supports concepts such as Option<T> (which has constructors Some(t) and None), which work well with matching and let-binding.
• I consider this code to be at least semi-idiomatic; I attempted to follow the established conventions of the language as I understood them—suggestions from Rust experts are welcome though!

Without further comment, here's the complete listing. The expected output is at the end of the post.

//------------------------------------------------------------------------------

const PEG_COUNT: usize = 5;
const POLE_COUNT: usize = 3;
const NO_PEG: u32 = 0xffffffff;


struct Peg(u32);


struct Pole {
    pegs: Vec,
    smallest: u32,
}


struct Scene {
    poles: Vec,
}


impl Pole {
    fn new() -> Pole {
        Pole {
            pegs: Vec::with_capacity(PEG_COUNT),
            smallest: NO_PEG,
        }
    }

    fn push(&mut self, p: Peg) -> bool {
        let Peg(v) = p;

        if v < self.smallest {
            self.pegs.push(p);
            self.smallest = v;
            true

        } else {
            println!("ERR: tried to push size {} onto pole {}.", v, self.smallest);
            false
        }
    }

    fn pop(&mut self) -> Option {
        let mut smallest = NO_PEG;
        let mut pegs = &mut self.pegs;
        let result = pegs.pop();

        for i in 0..(pegs.len()) {
            let Peg(v) = pegs[i];
            if v < smallest {
                smallest = v
            }
        }

        self.smallest = smallest;
        result
    }
}


impl Scene {
    fn new() -> Scene {
        let mut result = Scene {
            poles: Vec::with_capacity(POLE_COUNT),
        };

        for _ in 0..(POLE_COUNT) {
            result.poles.push(Pole::new());
        };

        for j in 0..(PEG_COUNT) {
            result.poles[0].push(Peg((PEG_COUNT - j) as u32));
        };

        result
    }

    fn move_peg(&mut self, from: usize, to: usize) -> bool {
        if let Some(Peg(v)) = self.poles[from].pop() {
            if self.poles[to].push(Peg(v)) {
                return true
            } else {
                self.poles[from].push(Peg(v));
            }
        }
        false
    }

    fn get(&self, pole: usize, peg: usize) -> Option<&Peg> {
        let poles = &self.poles;

        if poles.len() > pole {
            let pegs = &poles[pole].pegs;

            if pegs.len() > peg {
                return Some(&pegs[peg])
            }
        }
        None
    }

    fn show(&self) {
        println!("");
        for i in 0..(PEG_COUNT) {
            let mut string = "".to_string();

            for j in 0..(POLE_COUNT) {
                match self.get(j, (PEG_COUNT-1)-i) {

                    Some(&Peg(p)) => {
                        let fmt = format!("  {:02}  ", p).to_string();
                        string.push_str(fmt.as_slice());
                    }

                    None => {
                        string.push_str("  ||  ");
                    }
                }
            }

            println!("{}", string);
        }
        let mut string = "".to_string();
        for _ in 0..(POLE_COUNT) {
            string.push_str("_/||\\_")
        }
        println!("{}", string);
        println!("");
    }
}


//------------------------------------------------------------------------------

struct HanoiMove {
    from: usize,
    to: usize,
}


struct HanoiState {
    n: usize,
    from: usize,
    to: usize,
    via: usize,
}


struct HanoiSolver {
    step: usize,
    route: Vec,
}


impl HanoiState {
    fn new(n: usize, from: usize, to: usize, via: usize) -> HanoiState {
        HanoiState { n: n, from: from, to: to, via: via }
    }

    fn iter(&self, out: &mut Vec) {
        let &HanoiState { n, from, to, via } = self;
        if n > 0 {
            HanoiState::new(n - 1, from, via, to).iter(out);
            out.push(HanoiMove { from: from, to: to });
            HanoiState::new(n - 1, via, to, from).iter(out);
        }
    }
}


impl HanoiSolver {
    fn new(n: usize, from: usize, to: usize, via: usize) -> HanoiSolver {
        let mut result = HanoiSolver {
            step: 0,
            route: Vec::new(),
        };
        let state = HanoiState::new(n, from, to, via);
        state.iter(&mut result.route);
        result
    }
}


impl Iterator for HanoiSolver {
    type Item = HanoiMove;
    fn next(&mut self) -> Option {

        let &mut HanoiSolver { step, ref route } = self;

        if step < route.len() {
            let HanoiMove{ from, to } = route[step];
            self.step += 1;
            return Some(HanoiMove { from: from, to: to })
        }
        None
    }
}


//------------------------------------------------------------------------------

fn main() {
    let mut scene = Scene::new();
    let mut solver = HanoiSolver::new(PEG_COUNT, 0, 2, 1);

    scene.show();

    while let Some(HanoiMove { from, to }) = solver.next() {

        println!("Move from {} --> {}", from, to);
        scene.move_peg(from, to);
        scene.show();
    }
}

And if you can get that to compile and run, you should see some output like the following:

  01    ||    ||  
  02    ||    ||  
  03    ||    ||  
  04    ||    ||  
  05    ||    ||  
_/||\__/||\__/||\_

Move from 0 --> 2

  ||    ||    ||  
  02    ||    ||  
  03    ||    ||  
  04    ||    ||  
  05    ||    01  
_/||\__/||\__/||\_

Move from 0 --> 1

  ||    ||    ||  
  ||    ||    ||  
  03    ||    ||  
  04    ||    ||  
  05    02    01  
_/||\__/||\__/||\_

Move from 2 --> 1

  ||    ||    ||  
  ||    ||    ||  
  03    ||    ||  
  04    01    ||  
  05    02    ||  
_/||\__/||\__/||\_

Move from 0 --> 2

  ||    ||    ||  
  ||    ||    ||  
  ||    ||    ||  
  04    01    ||  
  05    02    03  
_/||\__/||\__/||\_

Move from 1 --> 0

  ||    ||    ||  
  ||    ||    ||  
  01    ||    ||  
  04    ||    ||  
  05    02    03  
_/||\__/||\__/||\_

Move from 1 --> 2

  ||    ||    ||  
  ||    ||    ||  
  01    ||    ||  
  04    ||    02  
  05    ||    03  
_/||\__/||\__/||\_

Move from 0 --> 2

  ||    ||    ||  
  ||    ||    ||  
  ||    ||    01  
  04    ||    02  
  05    ||    03  
_/||\__/||\__/||\_

Move from 0 --> 1

  ||    ||    ||  
  ||    ||    ||  
  ||    ||    01  
  ||    ||    02  
  05    04    03  
_/||\__/||\__/||\_

Move from 2 --> 1

  ||    ||    ||  
  ||    ||    ||  
  ||    ||    ||  
  ||    01    02  
  05    04    03  
_/||\__/||\__/||\_

Move from 2 --> 0

  ||    ||    ||  
  ||    ||    ||  
  ||    ||    ||  
  02    01    ||  
  05    04    03  
_/||\__/||\__/||\_

Move from 1 --> 0

  ||    ||    ||  
  ||    ||    ||  
  01    ||    ||  
  02    ||    ||  
  05    04    03  
_/||\__/||\__/||\_

Move from 2 --> 1

  ||    ||    ||  
  ||    ||    ||  
  01    ||    ||  
  02    03    ||  
  05    04    ||  
_/||\__/||\__/||\_

Move from 0 --> 2

  ||    ||    ||  
  ||    ||    ||  
  ||    ||    ||  
  02    03    ||  
  05    04    01  
_/||\__/||\__/||\_

Move from 0 --> 1

  ||    ||    ||  
  ||    ||    ||  
  ||    02    ||  
  ||    03    ||  
  05    04    01  
_/||\__/||\__/||\_

Move from 2 --> 1

  ||    ||    ||  
  ||    01    ||  
  ||    02    ||  
  ||    03    ||  
  05    04    ||  
_/||\__/||\__/||\_

Move from 0 --> 2

  ||    ||    ||  
  ||    01    ||  
  ||    02    ||  
  ||    03    ||  
  ||    04    05  
_/||\__/||\__/||\_

Move from 1 --> 0

  ||    ||    ||  
  ||    ||    ||  
  ||    02    ||  
  ||    03    ||  
  01    04    05  
_/||\__/||\__/||\_

Move from 1 --> 2

  ||    ||    ||  
  ||    ||    ||  
  ||    ||    ||  
  ||    03    02  
  01    04    05  
_/||\__/||\__/||\_

Move from 0 --> 2

  ||    ||    ||  
  ||    ||    ||  
  ||    ||    01  
  ||    03    02  
  ||    04    05  
_/||\__/||\__/||\_

Move from 1 --> 0

  ||    ||    ||  
  ||    ||    ||  
  ||    ||    01  
  ||    ||    02  
  03    04    05  
_/||\__/||\__/||\_

Move from 2 --> 1

  ||    ||    ||  
  ||    ||    ||  
  ||    ||    ||  
  ||    01    02  
  03    04    05  
_/||\__/||\__/||\_

Move from 2 --> 0

  ||    ||    ||  
  ||    ||    ||  
  ||    ||    ||  
  02    01    ||  
  03    04    05  
_/||\__/||\__/||\_

Move from 1 --> 0

  ||    ||    ||  
  ||    ||    ||  
  01    ||    ||  
  02    ||    ||  
  03    04    05  
_/||\__/||\__/||\_

Move from 1 --> 2

  ||    ||    ||  
  ||    ||    ||  
  01    ||    ||  
  02    ||    04  
  03    ||    05  
_/||\__/||\__/||\_

Move from 0 --> 2

  ||    ||    ||  
  ||    ||    ||  
  ||    ||    01  
  02    ||    04  
  03    ||    05  
_/||\__/||\__/||\_

Move from 0 --> 1

  ||    ||    ||  
  ||    ||    ||  
  ||    ||    01  
  ||    ||    04  
  03    02    05  
_/||\__/||\__/||\_

Move from 2 --> 1

  ||    ||    ||  
  ||    ||    ||  
  ||    ||    ||  
  ||    01    04  
  03    02    05  
_/||\__/||\__/||\_

Move from 0 --> 2

  ||    ||    ||  
  ||    ||    ||  
  ||    ||    03  
  ||    01    04  
  ||    02    05  
_/||\__/||\__/||\_

Move from 1 --> 0

  ||    ||    ||  
  ||    ||    ||  
  ||    ||    03  
  ||    ||    04  
  01    02    05  
_/||\__/||\__/||\_

Move from 1 --> 2

  ||    ||    ||  
  ||    ||    02  
  ||    ||    03  
  ||    ||    04  
  01    ||    05  
_/||\__/||\__/||\_

Move from 0 --> 2

  ||    ||    01  
  ||    ||    02  
  ||    ||    03  
  ||    ||    04  
  ||    ||    05  
_/||\__/||\__/||\_

Running with pointers II

(This is the second in an occasional series of explorations of some of the stranger areas of C++ syntax.)

Let's assume that we're all familiar with the RAII idiom (which is basically a fancy way to say "using destructors to manage resources correctly"). So let's consider the following listing, and ask ourselves: what output might it produce, and "Is it safe?"

#include <stdio.h> // for printf()
#include <memory> // for std::unique_ptr<>

struct Lock {
    void lock() {
        printf("Lock::lock()\n");
        data = std::unique_ptr<int>(new int(23));
    }

    void unlock() {
        printf("Lock::unlock()\n");
        data.release();
    }

protected:
    // valid during lock: using unique_ptr for safety
    std::unique_ptr<int> data;
};

// RAII for safety
struct AutoLock {
    AutoLock(Lock &l): l(l) { l.lock(); }
    ~AutoLock() { l.unlock(); }

    Lock &l;
};

struct SafeCode: Lock {
    void safe() {
        AutoLock(*this);
        // we can access the data now...
        printf("My data is safe here!\n");
        printf("Locked data = %i\n", *data);
    }
};

int main() {
    SafeCode s;
    s.safe();
    return 0;
}

We have a type called Lock that has lock() and unlock() methods. These methods guard a resource which is only valid when the lock is locked. (For our purposes, the 'resource' we're managing is the number 23, and it is accessible directly through a member variable—neither of these are particularly defensible design decisions, but can be ignored.) We're even using a fancy C++11 unique_ptr to manage our resource to make sure we don't get burned by raw pointer errors (which might be ironic if it wasn't a terrible analogy). AutoLock wraps the lock's API in its constructor and destructor, which should ensure that Lock::data should be valid for the lifetime of an AutoLock object.

The type SafeCode inherits from Lock and provides a method called safe() which demonstrates the usage of AutoLock, which ought to be safe, right? It's right there in the name of the function.
So we'd expect to see this:

Lock::lock()
My data is safe here!
Locked data = 23
Lock::unlock()

SPOILERS: No, it's not safe. What I actually see, compiling with gcc -std=c++11 on Ubuntu 14.04 is this:

Lock::lock()
Lock::unlock()
My data is safe here!
Segmentation fault (core dumped)

Ouch. So what went wrong? The problem is actually with the definition of the AutoLock object at the start of safe(). We forgot to give it a name, so it is immediately destroyed after its creation, and more importantly, before we try to access the data. If we give it a name (so AutoLock lock(*this); or even AutoLock _(*this); would suffice) it will survive until the end of the scope it's contained in (i.e. the end of the function safe()).

We'll need to go digging in the standard to find out more. Section 12.2 (Temporary objects) contains verbiage which would indicate that the anonymous AutoLock instance is "a temporary whose lifetime is not extended by being bound to a reference". Because it has no name, it cannot possibly be referenced again after its introduction, so the compiler is justified in placing the call to its destructor immediately after the object is constructed. (We will leave aside the question of why we are allowed to create an anonymous instance like this, and if this is ever legitimate—please post a comment if you have a situation where defining an anonymous temporary variable like this is a valid and useful technique.)

The use of unique_ptr<> is pretty much a red herring, I just threw that in to dissuade critiquing which might've resulted from int *data; in the definition of Lock. (And, I suppose, smart pointers are now standard, so we should use them given the option. Unless, I also suppose, you really are concerned about performance, and you have a profile trace demonstrating that the use of a smart pointer is your performance bottleneck. But this is a lot of parenthetical supposition.) One thing I will say though, is that at least unique_ptr causes the broken code to crash—with a raw pointer, the program happily reported that the value of data was zero, and continued to run to completion. Although given the nature of the bug, we could assume that literally anything could happen.

"Forget it Jake, it's undefined behaviour..."

Trigonometry in awk

I've been doing a lot of work with OpenGL recently, attempting to get some glBegin()/glEnd()-era 'rendering' code into some kind of shape where I can port it from desktop OpenGL to mobile and web platforms running OpenGL ES or WebGL. This basically meant throwing the existing code into a well, burning it, learning how to OpenGL properly and starting again, but that's all going quite well—I've even started writing shaders! ¹

This post, however, is not about that. Having got to a point where I have a basic 2D GL3.0/GLES2.0 framework in place, I wanted to actually draw something. Triangles are almost too easy to draw, and squares aren't much harder (you can either use glDrawArrays(GL_TRIANGLE_STRIP) or glDrawElements(GL_TRIANGLES)).

So, with mastery of 3 and 4 vertex shapes, I wanted to move on to the next challenge, which is obviously... a pentagon. But how to figure out the co-ordinates? The math behind regular polygons is pretty straightforward, so we just need to take sines and cosines of some angles. I thought that jumping into C++ for this was a bit over the top, and I wasn't in the mood to mess around with any 'batteries-included' interpreters. I just want something quick, light and iterative—agile, if you will. I wonder whether awk has any numeric capabilities...

Spoiler: It does!

#!/usr/bin/awk -f
BEGIN {
    PI = 3.141592654

    if("" == (SIDES = ARGV[1])) {
        SIDES = 5
    }
    if("" == (COMMENT = ARGV[2])) {
        COMMENT = "#"
    }

    print COMMENT " " SIDES "-sided regular polygon..."

    print COMMENT " vertices"
    for(n = 1; n <= SIDES; n++) {
        A = 2 * PI * n / SIDES
        printf "%.2f, %.2f,\n", cos(A), sin(A)
    }
    print COMMENT " texcoords"
    for(n = 1; n <= SIDES; n++) {
        A = 2 * PI * n / SIDES
        printf "%.2f, %.2f,\n", (.5 + cos(A)/2), (.5 + sin(A)/2)
    }
}

One of the niceties of awk is that there's no operator for string concatenation, you just glom string variables and constants together next to each other and it 'just works', which makes print statements a lot less noisy than most other languages. Another nice thing is that printf is available, and works exactly as you'd expect it would. Other than that, we only really need sin(), cos() and the ability to loop, and we're finished.

When run, this spits out data for vertex coordinates (ranging -1.0 to 1.0) and texture coordinates (ranging 0.0 to 1.0) for each point around the edge of a regular polygon (defaulting to a pentagon if no parameters are given).

$ ./poly.awk
# 5-sided regular polygon...
# vertices
0.31, 0.95,
-0.81, 0.59,
-0.81, -0.59,
0.31, -0.95,
1.00, 0.00,
# texcoords
0.65, 0.98,
0.10, 0.79,
0.10, 0.21,
0.65, 0.02,
1.00, 0.50,

It can generate coordinates for any number of sides, and there's even an optional parameter to change the comment syntax, so you can just copy and paste the output into the vertex array literal of your language of choice.

$ ./poly.awk 3 //
// 3-sided regular polygon...
// vertices
-0.50, 0.87,
-0.50, -0.87,
1.00, 0.00,
// texcoords
0.25, 0.93,
0.25, 0.07,
1.00, 0.50,

$ ./poly.awk 6 --
-- 6-sided regular polygon...
-- vertices
0.50, 0.87,
-0.50, 0.87,
-1.00, -0.00,
-0.50, -0.87,
0.50, -0.87,
1.00, 0.00,
-- texcoords
0.75, 0.93,
0.25, 0.93,
0.00, 0.50,
0.25, 0.07,
0.75, 0.07,
1.00, 0.50,

awk's execution model is geared towards reading files line-by-line, extracting patterns and processing them, so this isn't really playing to its strengths. But nevertheless, treating it like a high-level, loosely typed version of C, I was able to get from idea to implementation to refinement in about 10 minutes. (And then I was able to render a coloured, shaded OpenGL pentagon and it made me happy. I am easily pleased.) I think awk is a useful tool to get to know, seeing as it's almost certainly already installed on your machine².

The Android NDK goes as far as to use awk to build a full XML parser (of sorts), which is entertaining, if not a little bit bonkers.

Here's a terrible-looking graphic of the Emscripten-powered pentagon!

---

1 I should probably write about cross-platform shader development at some point, it's all manner of fun!^↩
2 Not you, Windows user! You'll have to make do with PowerShell.^↩

Setting up a fossil server

When I'm working on personal projects, I've usually used a pen and paper to keep track of design issues, bugs to be fixed and so on, but I've recently found myself wanting an actual issue tracking database. My requirements are actually pretty straightforward:

• Must be accessible from a browser
• No PHP
• Easy to set up
• Use SQLite as a database backend if possible (see previous point)

I did some searching and reading around, and I thought about Apache Bloodhound, but I was scared off by the installation instructions. I also briefly looked at Trac which Bloodhound is apparently a fork of, but again, a baffling and intimidating installation procedure left me cold.
Next up Bugzilla, which I spent about 20mins trying to set up, installed a lot of Perl modules, and got some incomprehensible (and even worse, un-google-able) timezone error, so I didn't even get as far as trying to set up an instance of Apache webserver, which I wasn't expecting to enjoy anyway. At least with this one, I tried!
During my earlier research, I had read about fossil, as if you type issue tracker SQLite into a search engine of your choice, fossil will be on the first page of results. This is because it and SQLite are both written by the same person. I'd disregarded fossil as its primary purpose seems to be as a DVCS that happens to have bug tracking (and a wiki!) as additional features on the side. However, it's very very easy to set up a fossil server from a standing start. So very easy, in fact that I managed to get it up and running in under ten minutes, on a server running Debian 6:
After sshing into the box, I installed the distribution version of fossil with apt-get, and created a new user called fossil (because I am terrible at naming things, it turns out).

$ su
# apt-get install fossil
# adduser fossil

Follow the adduser prompts with with password and other information as desired here…
Now, as the fossil user, create a new database in the home directory (called bugs.db—names; terrible).

# su fossil
$ fossil new ~/bugs.db

Make a note of the username/password for your admin account of the fossil site in the output from this command (the username is probably fossil if you specified that to adduser), as you won't be able to do anything useful to the server without admin access. At this point, we could start the server running, but we want to configure it to start up when the machine starts up, so we need to go back to root and edit rc.local:

$ exit
# vim /etc/rc.local

Add this line to the end:

su fossil -c 'fossil server ~/bugs.db'

That's literally all you need to do. Reboot the server and boom, the server should be listening on port 8080 when the server comes back up, and you can log in using the username and password noted earlier. If you want to be all fancy and route HTTP traffic from port 80 over to 8080, you can add another line to rc.local, just before you kick off the fossil server:

iptables -t nat -A PREROUTING -i venet0 -p tcp --dport 80 -j REDIRECT --to-port 8080

If you're anything like me, you'll probably want to spend the next hour or so tweaking the site's CSS and HTML templates and making it your own.
Fossil is a triumph of minimalism—it is literally one single executable file and one database file. It contains a DVCS, wiki, issue tracking and source control browser with a web interface. I'm primarily only interested in the bug tracking for the time being, as at the moment I still want to keep my source code in SVN. But, now that I have a fossil repository available to me, I might want to import my history and give myself the option to work offline, git-style. Another possibility is that I can use the fossil repository to hold releases of my projects, and I can accept and version control patches and bugfixes for each release. Having a (bare-bones) wiki up and running is also nice.
The moral of this story is that from an installation perspective, fossil definitely beats out the competition here. It's not as configurable or as extensible as other solutions, but that doesn't really matter to me if I can't get the other solutions to run in the first place!

Type tagging and SFINAE in C++

While it may sound like an onomatopoeia for somebody sneezing, SFINAE is a C++ idiom, standing for 'Substitution Failure Is Not An Error'. The idea is that when instantiating a template, if more than one instantiation is viable, then any other instantiations which would cause an error are not considered. As long as there is one valid instantiation, that instantiation will be used. In other words, the fact that some substitutions may fail is not enough to cause a(n) compilation error. A quick example to demonstrate this—let's assume we have declared the following template which expects to operate on types which contain an embedded type called SomeType:

template<typename T>struct Example {

    typename T::SomeType t;
};

struct Ok { typedef int SomeType; };

Example<Ok> ok; // perfectly fine

It should be fairly uncontroversial to point out that is not going to work with native types, such as int:

Example<int> i; // not so fine

But, if we were to provide an int-compatible instantiation, then the presence of the default instantiation isn't going to interfere with the use of the overridden version:

template<>struct Example<int> {
    int t;
};
Example<int> i; // fine now, default Example template is no longer considered.

This selection process can be used to choose programmatically between different template instantiations, based on the presence or absence of an embedded type (i.e. a tag type) in a type declaration. The syntax used to define these kinds of template mechanisms can often be somewhat opaque, so I devised a mechanism which conveniently wraps the type detection mechanism into a single macro, called TYPE_CHECK(). An example usage would be something like this:

TYPE_CHECK(Test1Check, T, TypeToCheck,
    static const bool VALUE = true, // Test1Check body when T::TypeToCheck exists
    static const bool VALUE = false); // Test1Check body default

This defines a template type called Test1Check<T>, containing a boolean constant VALUE which is true for any T where T::TypeToCheck exists, or false if it doesn't, so, in the following example, we would see output of "0, 1" from printf():

struct TestingF {};
struct TestingT { typedef void TypeToCheck; };

printf("%u, %u\n",  // prints "0, 1"
    Test1Check<TestingF>::VALUE,
    Test1Check<TestingT>::VALUE);

TYPE_CHECK() takes 5 arguments: the first and second are the name of the check type (Test1Check), and the type parameter (usually but not necessarily T). The macro will expand into a template struct definition (template<typename T>struct Test1Check { /*...*/ }; in this case). The third parameter is the name of the type we want to test for (i.e. the presence or absence of T::TypeToCheck), and the fourth and fifth parameters represent the body of this struct (the /*...*/ part) if the test type is present, or the default in the case it's not present.
We could rewrite our initial Example given above as follows, although it should now work for any type without an embedded T::SomeType, and not just int:

TYPE_CHECK(Example, T, SomeType,
    typename T::SomeType t,
    T t);

You can also use TYPE_CHECK() to embed functions into the check type, so that your program can operate differently depending on if the test type is present or not. You can use this to implement some fairly primitive compile-time reflection mechanisms.
One additional refinement worth mentioning is that if you have a compiler which supports C99-style variadic macros, it's possible to parenthesize the fourth and fifth arguments, which is occasionally useful if they need to contain commas—an example of this is in the test code provided below.
There's one additional macro called TYPE_CHECK_FRIEND(). It takes the name of a check defined by TYPE_CHECK() and this can be placed inside the body of a type if you want to give the check access to the internals of a type. Again, there's an example of this in the test code.
The TYPE_CHECK() implementation lives in a single header file, nominally called "type_check.h", which can be copied from here. You should be able to just paste it to a local file and start using it. It contains the two macros outlined above, and a few implementation details (anything in the namespace tc_ or starting with a tc_ prefix), which you can ignore. If you're using a compiler which doesn't support variadic macros, you should #define TYPE_CHECK_NO_VA_ARGS before #including it.
A simple 'test suite' can be copied from here, which shows a few different ways that this kind of mechanism can be used. As far as I'm concerned, this code is public domain, so feel free to do whatever you'd like with it.

Addendum 8.3.14:

I just noticed that my source code (which was hosted on hastebin.com) is no longer available there, so I've pushed the files to Dropbox instead, where hopefully they will remain accessible for the forseeable future. It should make it easier for me to publish updates as well - which is for the best as running the code through ideone reveals an issue with the TYPE_CHECK_FRIEND() macro in GCC 4.8.1, but 4.3.2 seems happy enough with it.

On casting the result of malloc()

It my be that a good way to drive traffic to your (relatively) new blog would be to find a contentious but ultimately minor technical argument and take sides, and so without further ado:

uint8_t *p = (uint8_t*)malloc(n);

There's a large amount of debate around casting the result of malloc(), and we're going to examine whether or not it's necessary. (The short answer is that it isn't, but we will explore why in more detail.) There are three main scenarios in which a cast of malloc() could be used, either in C or in C++, or in what we'll refer to as "C/C++" (a misguided attempt to write in both languages at once).

In C

This is fairly straightforward - the C standard (as of C89, at least) specifies that any void pointer can be implicitly converted to any other pointer type, so any cast would be unnecessary, so therefore we shouldn't add unnecessary casts to our code because casts are bad, so we should write the following:

uint8_t *p = malloc(n);

We can go slightly further than this if we want to allocate an instance of a specific type, rather than a buffer of arbitrary size, and we should phrase the call to malloc() thus:

Type *p = malloc(sizeof(*p));

In this case, the compiler can calculate the size we want to allocate for the object from the dereferenced pointer type. Some people would have you phrase that as:

Type *p = (Type*)malloc(sizeof(Type));

Which manages to be ugly, repetitive and fragile, mentioning the name of Type three times, where once would suffice. We should not listen to these people.
Another argument against casting in C is that if you've neglected to #include <stdlib.h>, then you would get a warning about a cast from int to a pointer type. This would be due to the compiler assuming that malloc() returns an int as it hasn't seen a prototype. This is technically true, but I would think that if you've neglected to include system header files, you'd have to be very unlucky if the worst outcome was getting a single warning (i.e. you will most likely have larger problems). And it seems that recent versions of GCC will give you a warning ("incompatible implicit declaration of built-in function ‘malloc’") if <stdlib.h> is missing, whether you cast the result of malloc() or not.

In C++

The argument in C++ is also fairly straightforward—while implicit casts of void pointers are verboten, there is really no need to use malloc() at all in C++, where new[] exists, and is much more typesafe:

uint8_t *p = new uint8_t[n];

And in the case of allocating an instance of a type we could write something like this (which will also allow you to pass arguments to the Type constructor):

Type *p = new Type(a, b, c);

In some limited circumstances, you may want to allocate memory for an object in an an unusual way, but you can still use a placement new on a void pointer in this kind of situation:

void *p = memalign(64, sizeof(Type));
Type *t = new(p) Type(a, b, c); // no casting required

In "C/C++"

One remaining argument which might be raised is that you'd like to write code which can be compiled with both a C compiler and a C++ compiler (simultaneously, perhaps?). In this case, people will try to convince you that you'd need to use malloc() for C compatibility, and you'll need to cast its result for C++ compatibility, so in this specific case, you really have no choice but to write:

uint8_t *p = (uint8_t*)malloc(n);

And these people are wrong, for two reasons. Firstly, if I genuinely need code which compiles to both languages, I'm going to use the preprocessor so I can work with the union of the idioms of both languages, rather than the intersection:

#ifdef __cplusplus
#define MY_MALLOC(type_, size_) static_cast<type_>(malloc(size_)) // ...or even "new type_[size_]"
#else//__cplusplus
#define MY_MALLOC(type_, size_) malloc(size_)
#endif//__cplusplus

//later...
uint8_t *p = MY_MALLOC(uint8_t, n);

But (secondly) there are very few reasons to do this kind of thing anyway - if you have some C code, just compile it with a C compiler and link it against your C++ application, possibly with some judicious use of extern "C" here and there.
So, in summary, there are no situations where it is necessary to cast the result of malloc()—it is at best redundant, and at worst actively detrimental to your code's quality.