* [jit] Documentation tweaks
@ 2014-10-07 17:51 David Malcolm
0 siblings, 0 replies; 2+ messages in thread
From: David Malcolm @ 2014-10-07 17:51 UTC (permalink / raw)
To: jit, gcc-patches; +Cc: David Malcolm
Committed to branch dmalcolm/jit:
gcc/jit/ChangeLog.jit:
* docs/internals/index.rst (Overview of code structure): Directly
include the comment from jit-common.h as rst, rather than as a
quoted C++ comment.
* jit-common.h: Convert the summary format to valid reStructured
text for inclusion by docs/internals/index.rst.
* notes.txt: Clarify where libgccjit.c, jit-recording.c and
jit-playback.c fit into the high-level diagram.
---
gcc/jit/ChangeLog.jit | 10 ++++++++++
gcc/jit/docs/internals/index.rst | 7 +++----
gcc/jit/jit-common.h | 12 +++++++-----
gcc/jit/notes.txt | 13 +++++++++----
4 files changed, 29 insertions(+), 13 deletions(-)
diff --git a/gcc/jit/ChangeLog.jit b/gcc/jit/ChangeLog.jit
index 4592002..1a76543 100644
--- a/gcc/jit/ChangeLog.jit
+++ b/gcc/jit/ChangeLog.jit
@@ -1,5 +1,15 @@
2014-10-07 David Malcolm <dmalcolm@redhat.com>
+ * docs/internals/index.rst (Overview of code structure): Directly
+ include the comment from jit-common.h as rst, rather than as a
+ quoted C++ comment.
+ * jit-common.h: Convert the summary format to valid reStructured
+ text for inclusion by docs/internals/index.rst.
+ * notes.txt: Clarify where libgccjit.c, jit-recording.c and
+ jit-playback.c fit into the high-level diagram.
+
+2014-10-07 David Malcolm <dmalcolm@redhat.com>
+
* Make-lang.in (jit_OBJS): Drop jit/internal-api.o.
Add jit/jit-recording.o and jit/jit-playback.o.
diff --git a/gcc/jit/docs/internals/index.rst b/gcc/jit/docs/internals/index.rst
index 3065c60..1e3952c 100644
--- a/gcc/jit/docs/internals/index.rst
+++ b/gcc/jit/docs/internals/index.rst
@@ -152,7 +152,6 @@ Overview of code structure
Here is a high-level summary from ``jit-common.h``:
- .. literalinclude:: ../../jit-common.h
- :start-after: /* Summary. */
- :end-before: namespace gcc {
- :language: c++
+.. include:: ../../jit-common.h
+ :start-after: This comment is included by the docs.
+ :end-before: End of comment for inclusion in the docs. */
diff --git a/gcc/jit/jit-common.h b/gcc/jit/jit-common.h
index 5c41ddd..58e4a8c 100644
--- a/gcc/jit/jit-common.h
+++ b/gcc/jit/jit-common.h
@@ -36,9 +36,9 @@ along with GCC; see the file COPYING3. If not see
const int NUM_GCC_JIT_TYPES = GCC_JIT_TYPE_FILE_PTR + 1;
-/* Summary. */
+/* This comment is included by the docs.
-/* In order to allow jit objects to be usable outside of a compile
+ In order to allow jit objects to be usable outside of a compile
whilst working with the existing structure of GCC's code the
C API is implemented in terms of a gcc::jit::recording::context,
which records the calls made to it.
@@ -79,15 +79,17 @@ const int NUM_GCC_JIT_TYPES = GCC_JIT_TYPE_FILE_PTR + 1;
During a playback, we associate objects from the recording with
their counterparts during this playback. For simplicity, we store this
- within the recording objects, as "void *m_playback_obj", casting it to
+ within the recording objects, as ``void *m_playback_obj``, casting it to
the appropriate playback object subclass. For these casts to make
sense, the two class hierarchies need to have the same structure.
- Note that the playback objects that "m_playback_obj" points to are
+ Note that the playback objects that ``m_playback_obj`` points to are
GC-allocated, but the recording objects don't own references:
these associations only exist within a part of the code where
the GC doesn't collect, and are set back to NULL before the GC can
- run. */
+ run.
+
+ End of comment for inclusion in the docs. */
namespace gcc {
diff --git a/gcc/jit/notes.txt b/gcc/jit/notes.txt
index 54dca8f..d337cb4 100644
--- a/gcc/jit/notes.txt
+++ b/gcc/jit/notes.txt
@@ -5,8 +5,13 @@ Client Code . Generated . libgccjit.so
â . . . .
ââââââââââââââââââââââââââ> . .
. . â . .
-
- . (record API calls) .
+ . . V . .
+ . . ââ> libgccjit.c .
+ . . â (error-checking).
+ . . â .
+ . . ââ> jit-recording.c
+ . . (record API calls)
+ . . <âââââââ .
. . â . .
<âââââââââââââââââââââââââââ . .
â . . . .
@@ -27,8 +32,8 @@ Client Code . Generated . libgccjit.so
. . . â .
..........................................â..................VVVVVVVVVVVVV...
. . . â . No GC in here
- . . . â .
- . . . (playback of API calls)
+ . . . â jit-playback.c
+ . . . â (playback of API calls)
. . . âââââââââââââââ> creation of functions,
. . . . types, expression trees
. . . <ââââââââââââââââ etc
--
1.7.11.7
^ permalink raw reply [flat|nested] 2+ messages in thread
* [jit] Documentation tweaks
@ 2014-09-29 15:59 David Malcolm
0 siblings, 0 replies; 2+ messages in thread
From: David Malcolm @ 2014-09-29 15:59 UTC (permalink / raw)
To: jit, gcc-patches; +Cc: David Malcolm
Committed to branch dmalcolm/jit:
gcc/jit/ChangeLog.jit:
* TODO.rst: Update.
* docs/topics/expressions.rst (gcc_jit_context_new_call): Add
a note clarifying the behavior of this entrypoint.
* docs/topics/functions.rst (Creating and using functions): Markup
fix.
(gcc_jit_block_add_assignment_op): Add an example.
---
gcc/jit/TODO.rst | 9 ++-------
gcc/jit/docs/topics/expressions.rst | 23 +++++++++++++++++++++++
gcc/jit/docs/topics/functions.rst | 13 +++++++++++--
3 files changed, 36 insertions(+), 9 deletions(-)
diff --git a/gcc/jit/TODO.rst b/gcc/jit/TODO.rst
index c1ea024..09c4d9d 100644
--- a/gcc/jit/TODO.rst
+++ b/gcc/jit/TODO.rst
@@ -29,12 +29,6 @@ API
gcc_jit_function_as_rvalue ()
-* clarify gcc_jit_function_add_eval()::
-
- (void)expression;
-
- and, indeed, clarify all of the other operations.
-
* expressing branch probabilies (like __builtin_expect)::
extern gcc_jit_rvalue *
@@ -99,7 +93,8 @@ Future milestones
* Detect and issue warnings/errors about uses of uninitialized variables
-* Warn about unused objects in a context (e.g. rvalues/lvalues)?
+* Warn about unused objects in a context (e.g. rvalues/lvalues)? (e.g.
+ for gcc_jit_context_new_call vs gcc_jit_block_add_eval)
Nice to have
============
diff --git a/gcc/jit/docs/topics/expressions.rst b/gcc/jit/docs/topics/expressions.rst
index 98d8e92..a95f5c9 100644
--- a/gcc/jit/docs/topics/expressions.rst
+++ b/gcc/jit/docs/topics/expressions.rst
@@ -364,6 +364,29 @@ Function calls
Given a function and the given table of argument rvalues, construct a
call to the function, with the result as an rvalue.
+ .. note::
+
+ :c:func:`gcc_jit_context_new_call` merely builds a
+ :c:type:`gcc_jit_rvalue` i.e. an expression that can be evaluated,
+ perhaps as part of a more complicated expression.
+ The call *won't* happen unless you add a statement to a function
+ that evaluates the expression.
+
+ For example, if you want to call a function and discard the result
+ (or to call a function with ``void`` return type), use
+ :c:func:`gcc_jit_block_add_eval`:
+
+ .. code-block:: c
+
+ /* Add "(void)printf (arg0, arg1);". */
+ gcc_jit_block_add_eval (
+ block, NULL,
+ gcc_jit_context_new_call (
+ ctxt,
+ NULL,
+ printf_func,
+ 2, args));
+
Type-coercion
*************
diff --git a/gcc/jit/docs/topics/functions.rst b/gcc/jit/docs/topics/functions.rst
index 15c895a..aa0c069 100644
--- a/gcc/jit/docs/topics/functions.rst
+++ b/gcc/jit/docs/topics/functions.rst
@@ -18,7 +18,7 @@
.. default-domain:: c
Creating and using functions
-================================
+============================
Params
------
@@ -224,7 +224,16 @@ Statements
lvalue *= rvalue;
lvalue /= rvalue;
- etc.
+ etc. For example:
+
+ .. code-block:: c
+
+ /* "i++" */
+ gcc_jit_block_add_assignment_op (
+ loop_body, NULL,
+ i,
+ GCC_JIT_BINARY_OP_PLUS,
+ gcc_jit_context_one (ctxt, int_type));
.. function:: void\
gcc_jit_block_add_comment (gcc_jit_block *block,\
--
1.7.11.7
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2014-10-07 17:51 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-10-07 17:51 [jit] Documentation tweaks David Malcolm
-- strict thread matches above, loose matches on Subject: below --
2014-09-29 15:59 David Malcolm
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).