This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
[jit] Improvements to documentation.
- From: David Malcolm <dmalcolm at redhat dot com>
- To: gcc-patches at gcc dot gnu dot org, jit at gcc dot gnu dot org
- Cc: David Malcolm <dmalcolm at redhat dot com>
- Date: Tue, 15 Oct 2013 20:36:51 -0400
- Subject: [jit] Improvements to documentation.
- Authentication-results: sourceware.org; auth=none
Committed to dmalcolm/jit branch.
gcc/jit/
* libgccjit.h (gcc_jit_location): Rewrite comment to reflect
that this part of the API is now implemented.
("Functions for use within the code factory."): Add notes on
memory-management and lifetimes.
* notes.txt: Update diagram to show handle_locations.
---
gcc/jit/ChangeLog.jit | 8 ++++++++
gcc/jit/libgccjit.h | 26 +++++++++++++++++---------
gcc/jit/notes.txt | 5 +++++
3 files changed, 30 insertions(+), 9 deletions(-)
diff --git a/gcc/jit/ChangeLog.jit b/gcc/jit/ChangeLog.jit
index 18101f1..da3e75a 100644
--- a/gcc/jit/ChangeLog.jit
+++ b/gcc/jit/ChangeLog.jit
@@ -1,5 +1,13 @@
2013-10-15 David Malcolm <dmalcolm@redhat.com>
+ * libgccjit.h (gcc_jit_location): Rewrite comment to reflect
+ that this part of the API is now implemented.
+ ("Functions for use within the code factory."): Add notes on
+ memory-management and lifetimes.
+ * notes.txt: Update diagram to show handle_locations.
+
+2013-10-15 David Malcolm <dmalcolm@redhat.com>
+
* TODO.rst: Update.
2013-10-14 David Malcolm <dmalcolm@redhat.com>
diff --git a/gcc/jit/libgccjit.h b/gcc/jit/libgccjit.h
index a17ab09..8985b8f 100644
--- a/gcc/jit/libgccjit.h
+++ b/gcc/jit/libgccjit.h
@@ -30,17 +30,17 @@ typedef struct gcc_jit_context gcc_jit_context;
/* A gcc_jit_result encapsulates the result of a compilation. */
typedef struct gcc_jit_result gcc_jit_result;
-/* A gcc_jit_location will encapsulate a source code location, so that
- you can associated locations in your language with statements in the
- JIT-compiled code, allowing the debugger to single-step through
- your language.
+/* A gcc_jit_location encapsulates a source code location, so that
+ you can (optionally) associate locations in your language with
+ statements in the JIT-compiled code, allowing the debugger to
+ single-step through your language.
- This part of the API is a placeholder to allow future expansion
- without breaking ABI: there currently is no way of creating a
- gcc_jit_location.
+ Note that to do so, you also need to enable
+ GCC_JIT_BOOL_OPTION_DEBUGINFO
+ on the gcc_jit_context.
- For now you must pass NULL into parameters expecting a
- (gcc_jit_location *). */
+ gcc_jit_location instances are optional; you can always pass
+ NULL. */
typedef struct gcc_jit_location gcc_jit_location;
/* A gcc_jit_type encapsulates a type e.g. "int" or a "struct foo*". */
@@ -235,6 +235,14 @@ gcc_jit_result_release (gcc_jit_result *result);
/**********************************************************************
Functions for use within the code factory.
+
+ All objects created by these functions are cleaned up for you, after
+ your code-creation hook returns. Note that this means you can't hold
+ references to them for use after you return from your callback.
+
+ All (const char *) string arguments passed to these functions are
+ copied, so you don't need to keep them around. Note that this *isn't*
+ the case for other parts of the API.
**********************************************************************/
/* Creating source code locations for use by the debugger.
Line and column numbers are 1-based. */
diff --git a/gcc/jit/notes.txt b/gcc/jit/notes.txt
index 6d1288f..2c225ce 100644
--- a/gcc/jit/notes.txt
+++ b/gcc/jit/notes.txt
@@ -38,6 +38,11 @@ Client Code . Generated . libgccjit.so
âetc . . . .
â . . . .
ââââââââââââââââââââââââââââââââââ> .
+Return from client callback . â .
+ . . . â .
+ . . . â(handle_locations: add locations to
+ . . . â linemap and associate them with trees)
+ . . . â .
. . . â . No GC in here
..........................................â..................AAAAAAAAAAAAA...
. . . â for each function
--
1.7.11.7