Mercurial > hg > truffle
changeset 22195:09d91119929f
Documenting the connection between createContext, createFindContextNode and findContext and a trick how to get to the context on a slow path
author | Jaroslav Tulach <jaroslav.tulach@oracle.com> |
---|---|
date | Thu, 24 Sep 2015 15:50:38 +0200 |
parents | 7afb5e5cc3ca |
children | 364e3f024643 |
files | truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/TruffleLanguage.java |
diffstat | 1 files changed, 14 insertions(+), 6 deletions(-) [+] |
line wrap: on
line diff
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/TruffleLanguage.java Thu Sep 24 14:48:26 2015 +0200 +++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/TruffleLanguage.java Thu Sep 24 15:50:38 2015 +0200 @@ -106,11 +106,16 @@ /** * Creates internal representation of the executing context suitable for given environment. Each * time the {@link TruffleLanguage language} is used by a new - * {@link com.oracle.truffle.api.vm.TruffleVM} or in a new thread, the system calls this method - * to let the {@link TruffleLanguage language} prepare for <em>execution</em>. The returned - * execution context is completely language specific; it is however expected it will contain - * reference to here-in provided <code>env</code> and adjust itself according to parameters - * provided by the <code>env</code> object. + * {@link com.oracle.truffle.api.vm.PolyglotEngine} or in a new thread, the system calls this + * method to let the {@link TruffleLanguage language} prepare for <em>execution</em>. The + * returned execution context is completely language specific; it is however expected it will + * contain reference to here-in provided <code>env</code> and adjust itself according to + * parameters provided by the <code>env</code> object. + * <p> + * The standard way of accessing the here-in generated context is to create a {@link Node} and + * insert it into own AST hierarchy - use {@link #createFindContextNode()} to obtain the + * {@link Node findNode} and later {@link #findContext(com.oracle.truffle.api.nodes.Node) + * findContext(findNode)} to get back your language context. * * @param env the environment the language is supposed to operate in * @return internal data of the language in given environment @@ -215,7 +220,10 @@ } /** - * Uses the {@link #createFindContextNode()} node to obtain the current context. + * Uses the {@link #createFindContextNode()} node to obtain the current context. In case you + * don't care about performance (e.g. your are on a slow execution path), you can chain the + * calls directly as <code>findContext({@link #createFindContextNode()})</code> and forget the + * node all together. * * @param n the node created by this language's {@link #createFindContextNode()} * @return the context created by