From 301c5141f416e7adf06cc9e3f97f90af0ba11116 Mon Sep 17 00:00:00 2001
From: David Malcolm <dmalcolm@redhat.com>
Date: Thu, 22 Jan 2015 15:02:17 -0500
Subject: [PATCH] Call gcc_jit_result_release; start documenting gccjit.Result

---
 doc/conf.py       |  2 +-
 doc/results.rst   | 33 ++++++++++++++++++++++++++++++---
 gccjit/gccjit.pyx |  3 +++
 3 files changed, 34 insertions(+), 4 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index d73667a..4c20deb 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -41,7 +41,7 @@
 
 # General information about the project.
 project = u'gccjit'
-copyright = u'2014, David Malcolm'
+copyright = u'2014-2015, David Malcolm'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
diff --git a/doc/results.rst b/doc/results.rst
index 21e35e7..12db302 100644
--- a/doc/results.rst
+++ b/doc/results.rst
@@ -1,5 +1,5 @@
-.. Copyright 2014 David Malcolm <dmalcolm@redhat.com>
-   Copyright 2014 Red Hat, Inc.
+.. Copyright 2014-2015 David Malcolm <dmalcolm@redhat.com>
+   Copyright 2014-2015 Red Hat, Inc.
 
    This is free software: you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by
@@ -20,7 +20,34 @@ Compilation results
 
 .. py:class:: gccjit.Result
 
+   A :py:class:`gccjit.Result` encapsulates the result of compiling a
+   :py:class:`gccjit.Context` in-memory, and the lifetimes of any
+   machine code functions or globals that are within the result.
+
    .. py:method:: get_code(funcname)
 
-      .. TODO
+      Locate the given function within the built machine code.
+
+      Functions are looked up by name.  For this to succeed, a function
+      with a name matching `funcname` must have been created on
+      `result`'s context (or a parent context) via a call to
+      :py:meth:`gccjit.Context.new_function` with `kind`
+      :py:data:`gccjit.FunctionKind.EXPORTED`.
+
+      .. error-handling?
+
+      The returned value is an
+      `int`, actually a pointer to the machine code within the
+      address space of the process.  This will need to be wrapped up
+      with `ctypes` to be callable::
+
+         import ctypes
+
+         # "[int] -> int" functype:
+         int_int_func_type = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_int)
+         code = int_int_func_type(jit_result.get_code(b"square"))
+         assert code(5) == 25
 
+      The code has the same lifetime as the :py:class:`gccjit.Result`
+      instance; the pointer becomes invalid when the result instance
+      is cleaned up.
diff --git a/gccjit/gccjit.pyx b/gccjit/gccjit.pyx
index f86b763..4e805de 100644
--- a/gccjit/gccjit.pyx
+++ b/gccjit/gccjit.pyx
@@ -415,6 +415,9 @@ cdef class Result:
     def __cinit__(self):
         self._c_result = NULL
 
+    def __dealloc__(self):
+        c_api.gcc_jit_result_release(self._c_result)
+
     cdef _set_c_ptr(self, c_api.gcc_jit_result* c_result):
         self._c_result = c_result