{"action":"created","comment":{"url":"https://api.github.com/repos/graalvm/truffle/pulls/comments/52456761","id":52456761,"diff_hunk":"@@ -0,0 +1,101 @@\n+/*\n+ * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.\n+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.\n+ *\n+ * This code is free software; you can redistribute it and/or modify it\n+ * under the terms of the GNU General Public License version 2 only, as\n+ * published by the Free Software Foundation.  Oracle designates this\n+ * particular file as subject to the \"Classpath\" exception as provided\n+ * by Oracle in the LICENSE file that accompanied this code.\n+ *\n+ * This code is distributed in the hope that it will be useful, but WITHOUT\n+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or\n+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License\n+ * version 2 for more details (a copy is included in the LICENSE file that\n+ * accompanied this code).\n+ *\n+ * You should have received a copy of the GNU General Public License version\n+ * 2 along with this work; if not, write to the Free Software Foundation,\n+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.\n+ *\n+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA\n+ * or visit www.oracle.com if you need additional information or have any\n+ * questions.\n+ */\n+package com.oracle.truffle.api.instrumentation;\n+\n+import java.lang.annotation.ElementType;\n+import java.lang.annotation.Retention;\n+import java.lang.annotation.RetentionPolicy;\n+import java.lang.annotation.Target;\n+\n+import com.oracle.truffle.api.instrumentation.InstrumentableFactory.WrapperNode;\n+import com.oracle.truffle.api.nodes.Node;\n+import com.oracle.truffle.api.source.SourceSection;\n+\n+/**\n+ * <p>\n+ * Marks a guest language AST node class as instrumentable. An instrumentable node must provide a\n+ * {@link SourceSection} and a {@link #factory() wrapper factory} to create a wrapper for the\n+ * instrumentable node. Wrapper factories can be inherited by subclasses.\n+ * </p>\n+ * <p>\n+ * {@link Instrumentable} nodes must extend {@link Node}. The instrumentation framework will\n+ * {@link Node#replace(Node) replace} the instrumentable node with a {@link WrapperNode} and\n+ * delegate to the original node. For that at least one method starting with execute must be\n+ * non-private and non-final.\n+ * </p>\n+ * <p>\n+ * Example for a minimal implementation of an {@link Instrumentable instrumentable} node with a\n+ * generated wrapper.\n+ *\n+ * <pre>\n+ * &#064;Instrumentable(factory = BaseNodeWrapper.class)\n+ * public abstract class BaseNode extends Node {\n+ *     public abstract Object execute(VirtualFrame frame);\n+ * }\n+ * </pre>\n+ *\n+ * If the instrumentable node requires more than one parameter it the constructor it can either\n+ * provide a default constructor or it can also provide a copy constructor. For example:\n+ *\n+ * <pre>\n+ * &#064;Instrumentable(factory = BaseNodeWrapper.class)\n+ * public abstract class BaseNode extends Node {\n+ *     private final String addtionalData;\n+ *\n+ *     public BaseNode(String additonalData) {\n+ *         this.additionalData = additionalData;\n+ *     }\n+ *\n+ *     public BaseNode(BaseNode delegate) {\n+ *         this.additionalData = delegate.additionalData;\n+ *     }\n+ *\n+ *     public abstract Object execute(VirtualFrame frame);\n+ * }\n+ * </pre>\n+ *\n+ * @see WrapperNode\n+ * @see ProbeNode\n+ */","path":"truffle/com.oracle.truffle.api.instrumentation/src/com/oracle/truffle/api/instrumentation/Instrumentable.java","position":81,"original_position":81,"commit_id":"c4cbc5097b1b86f0b6ca8e5ae3e8cd9b7015b1bc","original_commit_id":"94cef9413729399a7aaee679483721e9e2c659d0","user":{"login":"chumer","id":4346215,"avatar_url":"https://avatars.githubusercontent.com/u/4346215?v=3","gravatar_id":"","url":"https://api.github.com/users/chumer","html_url":"https://github.com/chumer","followers_url":"https://api.github.com/users/chumer/followers","following_url":"https://api.github.com/users/chumer/following{/other_user}","gists_url":"https://api.github.com/users/chumer/gists{/gist_id}","starred_url":"https://api.github.com/users/chumer/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chumer/subscriptions","organizations_url":"https://api.github.com/users/chumer/orgs","repos_url":"https://api.github.com/users/chumer/repos","events_url":"https://api.github.com/users/chumer/events{/privacy}","received_events_url":"https://api.github.com/users/chumer/received_events","type":"User","site_admin":false},"body":"added a paragraph","created_at":"2016-02-10T13:34:43Z","updated_at":"2016-02-10T13:34:43Z","html_url":"https://github.com/graalvm/truffle/pull/1#discussion_r52456761","pull_request_url":"https://api.github.com/repos/graalvm/truffle/pulls/1","_links":{"self":{"href":"https://api.github.com/repos/graalvm/truffle/pulls/comments/52456761"},"html":{"href":"https://github.com/graalvm/truffle/pull/1#discussion_r52456761"},"pull_request":{"href":"https://api.github.com/repos/graalvm/truffle/pulls/1"}}},"pull_request":{"url":"https://api.github.com/repos/graalvm/truffle/pulls/1","id":56281148,"html_url":"https://github.com/graalvm/truffle/pull/1","diff_url":"https://github.com/graalvm/truffle/pull/1.diff","patch_url":"https://github.com/graalvm/truffle/pull/1.patch","issue_url":"https://api.github.com/repos/graalvm/truffle/issues/1","number":1,"state":"open","locked":false,"title":"Feature/instrumentation api","user":{"login":"chumer","id":4346215,"avatar_url":"https://avatars.githubusercontent.com/u/4346215?v=3","gravatar_id":"","url":"https://api.github.com/users/chumer","html_url":"https://github.com/chumer","followers_url":"https://api.github.com/users/chumer/followers","following_url":"https://api.github.com/users/chumer/following{/other_user}","gists_url":"https://api.github.com/users/chumer/gists{/gist_id}","starred_url":"https://api.github.com/users/chumer/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chumer/subscriptions","organizations_url":"https://api.github.com/users/chumer/orgs","repos_url":"https://api.github.com/users/chumer/repos","events_url":"https://api.github.com/users/chumer/events{/privacy}","received_events_url":"https://api.github.com/users/chumer/received_events","type":"User","site_admin":false},"body":"Here it is: the new instrumentation framework. It is the result of several sessions/discussions/walkthroughs with [~mlvdv] and [~jtulach].\r\n\r\n*Reading Recommendation:*\r\n\r\nIf you are not interested in the details skip over to the example uses in com.oracle.truffle.api.instrumentation.examples they should give the best idea.\r\n\r\nFor everybody else:\r\n1) Start reading with the package-info.java and then follow the references to explore the API. \r\n2) Look at the changes in PolyglotEngine on how users can instrument their applications.\r\n3) Look the examples in com.oracle.truffle.api.instrumentation.examples.\r\n4) Look at the changes to SimpleLanguage on how to see how languages can adopt it.\r\n5) Look at the instrumentation tests\r\n6) Look at the instrumentation implementation in InstrumentationHandler\r\n7) Look at changes to DefaultCallTarget to see how lazy instrumentation works\r\n8) Look at the implementation of the annotation processors: GenerateWrapperNodeProcessor and InstrumentationRegistrationProcessor.\r\n\r\nThere is also a trace mode (InstrumentationHandler#TRACE) that should make it easier to understand what is going on.\r\n\r\n\r\n*New and Noteworthy:*\r\no) Filter expression language for source sections with tags that do all the syntax probing/synchronization automatically and language agnostically (see SourceSectionFilter, Instrumenter).\r\no) Everything is now lazy. Wrappers are created only for places which are actually instrumented and which were executed at least once. Wrappers are updated lazy on next/first execution and removed if not needed anymore.\r\no) Fixed set of instrumentation tags for guest languages to adopt.\r\no) Event bindings for language implementations that have special privileges to implement language features with the framework (see InstrumentationLanguage).\r\no) Creation/disposal of instruments in PolyglotEngine and out,err,in for instrumentations.\r\no) Only instrumented RootNode instances are tracked. No tracking of anything else.\r\no) Easy dispose of event bindings. Automatic binding dispose for instrumentations on removal.\r\no) Language agnostic annotation processor for generating wrappers (see @Instrumentable, SL implementation)\r\n\r\n\r\n*Specific review questions:*\r\n\r\nA) Which use cases do you have that are not yet covered in the API?\r\nB) Which use cases do you see that are now covered which were not covered before?\r\nC) How can the implementation/API be improved/simplified?\r\nD) How could the naming be improved? (consistency, intuition, the hardest part :-) )\r\nE) Do you see issues in evolving of this API?\r\nF) How can the documentation be improved?\r\nG) Do you have ideas for tools (try to build them)?\r\n\r\n*Open/Known Issues:*\r\n\r\na) The Registration annotation processor does not work with incremental compiling.\r\n\r\n*Migration strategy/Next steps:*\r\n\r\nAfter taking your feedback into account I plan to push this through (if nobody objects). The old instrumentation framework will then be deprecated and removed later on. Old and new can live side-by-side for a while during adoption of the languages.\r\n\r\nThanks in advance to the reviewers.","created_at":"2016-01-17T16:21:10Z","updated_at":"2016-02-10T13:34:43Z","closed_at":null,"merged_at":null,"merge_commit_sha":"5614263ce4aff1f65b24947de0e5b89c59b6f3c1","assignee":{"login":"chumer","id":4346215,"avatar_url":"https://avatars.githubusercontent.com/u/4346215?v=3","gravatar_id":"","url":"https://api.github.com/users/chumer","html_url":"https://github.com/chumer","followers_url":"https://api.github.com/users/chumer/followers","following_url":"https://api.github.com/users/chumer/following{/other_user}","gists_url":"https://api.github.com/users/chumer/gists{/gist_id}","starred_url":"https://api.github.com/users/chumer/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chumer/subscriptions","organizations_url":"https://api.github.com/users/chumer/orgs","repos_url":"https://api.github.com/users/chumer/repos","events_url":"https://api.github.com/users/chumer/events{/privacy}","received_events_url":"https://api.github.com/users/chumer/received_events","type":"User","site_admin":false},"milestone":null,"commits_url":"https://api.github.com/repos/graalvm/truffle/pulls/1/commits","review_comments_url":"https://api.github.com/repos/graalvm/truffle/pulls/1/comments","review_comment_url":"https://api.github.com/repos/graalvm/truffle/pulls/comments{/number}","comments_url":"https://api.github.com/repos/graalvm/truffle/issues/1/comments","statuses_url":"https://api.github.com/repos/graalvm/truffle/statuses/c4cbc5097b1b86f0b6ca8e5ae3e8cd9b7015b1bc","head":{"label":"graalvm:feature/instrumentation_api","ref":"feature/instrumentation_api","sha":"c4cbc5097b1b86f0b6ca8e5ae3e8cd9b7015b1bc","user":{"login":"graalvm","id":10176827,"avatar_url":"https://avatars.githubusercontent.com/u/10176827?v=3","gravatar_id":"","url":"https://api.github.com/users/graalvm","html_url":"https://github.com/graalvm","followers_url":"https://api.github.com/users/graalvm/followers","following_url":"https://api.github.com/users/graalvm/following{/other_user}","gists_url":"https://api.github.com/users/graalvm/gists{/gist_id}","starred_url":"https://api.github.com/users/graalvm/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/graalvm/subscriptions","organizations_url":"https://api.github.com/users/graalvm/orgs","repos_url":"https://api.github.com/users/graalvm/repos","events_url":"https://api.github.com/users/graalvm/events{/privacy}","received_events_url":"https://api.github.com/users/graalvm/received_events","type":"Organization","site_admin":false},"repo":{"id":49662222,"name":"truffle","full_name":"graalvm/truffle","owner":{"login":"graalvm","id":10176827,"avatar_url":"https://avatars.githubusercontent.com/u/10176827?v=3","gravatar_id":"","url":"https://api.github.com/users/graalvm","html_url":"https://github.com/graalvm","followers_url":"https://api.github.com/users/graalvm/followers","following_url":"https://api.github.com/users/graalvm/following{/other_user}","gists_url":"https://api.github.com/users/graalvm/gists{/gist_id}","starred_url":"https://api.github.com/users/graalvm/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/graalvm/subscriptions","organizations_url":"https://api.github.com/users/graalvm/orgs","repos_url":"https://api.github.com/users/graalvm/repos","events_url":"https://api.github.com/users/graalvm/events{/privacy}","received_events_url":"https://api.github.com/users/graalvm/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/graalvm/truffle","description":"The Truffle Language Implementation Framework","fork":false,"url":"https://api.github.com/repos/graalvm/truffle","forks_url":"https://api.github.com/repos/graalvm/truffle/forks","keys_url":"https://api.github.com/repos/graalvm/truffle/keys{/key_id}","collaborators_url":"https://api.github.com/repos/graalvm/truffle/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/graalvm/truffle/teams","hooks_url":"https://api.github.com/repos/graalvm/truffle/hooks","issue_events_url":"https://api.github.com/repos/graalvm/truffle/issues/events{/number}","events_url":"https://api.github.com/repos/graalvm/truffle/events","assignees_url":"https://api.github.com/repos/graalvm/truffle/assignees{/user}","branches_url":"https://api.github.com/repos/graalvm/truffle/branches{/branch}","tags_url":"https://api.github.com/repos/graalvm/truffle/tags","blobs_url":"https://api.github.com/repos/graalvm/truffle/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/graalvm/truffle/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/graalvm/truffle/git/refs{/sha}","trees_url":"https://api.github.com/repos/graalvm/truffle/git/trees{/sha}","statuses_url":"https://api.github.com/repos/graalvm/truffle/statuses/{sha}","languages_url":"https://api.github.com/repos/graalvm/truffle/languages","stargazers_url":"https://api.github.com/repos/graalvm/truffle/stargazers","contributors_url":"https://api.github.com/repos/graalvm/truffle/contributors","subscribers_url":"https://api.github.com/repos/graalvm/truffle/subscribers","subscription_url":"https://api.github.com/repos/graalvm/truffle/subscription","commits_url":"https://api.github.com/repos/graalvm/truffle/commits{/sha}","git_commits_url":"https://api.github.com/repos/graalvm/truffle/git/commits{/sha}","comments_url":"https://api.github.com/repos/graalvm/truffle/comments{/number}","issue_comment_url":"https://api.github.com/repos/graalvm/truffle/issues/comments{/number}","contents_url":"https://api.github.com/repos/graalvm/truffle/contents/{+path}","compare_url":"https://api.github.com/repos/graalvm/truffle/compare/{base}...{head}","merges_url":"https://api.github.com/repos/graalvm/truffle/merges","archive_url":"https://api.github.com/repos/graalvm/truffle/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/graalvm/truffle/downloads","issues_url":"https://api.github.com/repos/graalvm/truffle/issues{/number}","pulls_url":"https://api.github.com/repos/graalvm/truffle/pulls{/number}","milestones_url":"https://api.github.com/repos/graalvm/truffle/milestones{/number}","notifications_url":"https://api.github.com/repos/graalvm/truffle/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/graalvm/truffle/labels{/name}","releases_url":"https://api.github.com/repos/graalvm/truffle/releases{/id}","deployments_url":"https://api.github.com/repos/graalvm/truffle/deployments","created_at":"2016-01-14T17:11:35Z","updated_at":"2016-02-09T20:45:29Z","pushed_at":"2016-02-10T13:00:45Z","git_url":"git://github.com/graalvm/truffle.git","ssh_url":"git@github.com:graalvm/truffle.git","clone_url":"https://github.com/graalvm/truffle.git","svn_url":"https://github.com/graalvm/truffle","homepage":"","size":20463,"stargazers_count":24,"watchers_count":24,"language":"Java","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":14,"mirror_url":null,"open_issues_count":9,"forks":14,"open_issues":9,"watchers":24,"default_branch":"master"}},"base":{"label":"graalvm:master","ref":"master","sha":"67c4830f8b542875fc99778cc17f17f963d49efc","user":{"login":"graalvm","id":10176827,"avatar_url":"https://avatars.githubusercontent.com/u/10176827?v=3","gravatar_id":"","url":"https://api.github.com/users/graalvm","html_url":"https://github.com/graalvm","followers_url":"https://api.github.com/users/graalvm/followers","following_url":"https://api.github.com/users/graalvm/following{/other_user}","gists_url":"https://api.github.com/users/graalvm/gists{/gist_id}","starred_url":"https://api.github.com/users/graalvm/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/graalvm/subscriptions","organizations_url":"https://api.github.com/users/graalvm/orgs","repos_url":"https://api.github.com/users/graalvm/repos","events_url":"https://api.github.com/users/graalvm/events{/privacy}","received_events_url":"https://api.github.com/users/graalvm/received_events","type":"Organization","site_admin":false},"repo":{"id":49662222,"name":"truffle","full_name":"graalvm/truffle","owner":{"login":"graalvm","id":10176827,"avatar_url":"https://avatars.githubusercontent.com/u/10176827?v=3","gravatar_id":"","url":"https://api.github.com/users/graalvm","html_url":"https://github.com/graalvm","followers_url":"https://api.github.com/users/graalvm/followers","following_url":"https://api.github.com/users/graalvm/following{/other_user}","gists_url":"https://api.github.com/users/graalvm/gists{/gist_id}","starred_url":"https://api.github.com/users/graalvm/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/graalvm/subscriptions","organizations_url":"https://api.github.com/users/graalvm/orgs","repos_url":"https://api.github.com/users/graalvm/repos","events_url":"https://api.github.com/users/graalvm/events{/privacy}","received_events_url":"https://api.github.com/users/graalvm/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/graalvm/truffle","description":"The Truffle Language Implementation Framework","fork":false,"url":"https://api.github.com/repos/graalvm/truffle","forks_url":"https://api.github.com/repos/graalvm/truffle/forks","keys_url":"https://api.github.com/repos/graalvm/truffle/keys{/key_id}","collaborators_url":"https://api.github.com/repos/graalvm/truffle/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/graalvm/truffle/teams","hooks_url":"https://api.github.com/repos/graalvm/truffle/hooks","issue_events_url":"https://api.github.com/repos/graalvm/truffle/issues/events{/number}","events_url":"https://api.github.com/repos/graalvm/truffle/events","assignees_url":"https://api.github.com/repos/graalvm/truffle/assignees{/user}","branches_url":"https://api.github.com/repos/graalvm/truffle/branches{/branch}","tags_url":"https://api.github.com/repos/graalvm/truffle/tags","blobs_url":"https://api.github.com/repos/graalvm/truffle/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/graalvm/truffle/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/graalvm/truffle/git/refs{/sha}","trees_url":"https://api.github.com/repos/graalvm/truffle/git/trees{/sha}","statuses_url":"https://api.github.com/repos/graalvm/truffle/statuses/{sha}","languages_url":"https://api.github.com/repos/graalvm/truffle/languages","stargazers_url":"https://api.github.com/repos/graalvm/truffle/stargazers","contributors_url":"https://api.github.com/repos/graalvm/truffle/contributors","subscribers_url":"https://api.github.com/repos/graalvm/truffle/subscribers","subscription_url":"https://api.github.com/repos/graalvm/truffle/subscription","commits_url":"https://api.github.com/repos/graalvm/truffle/commits{/sha}","git_commits_url":"https://api.github.com/repos/graalvm/truffle/git/commits{/sha}","comments_url":"https://api.github.com/repos/graalvm/truffle/comments{/number}","issue_comment_url":"https://api.github.com/repos/graalvm/truffle/issues/comments{/number}","contents_url":"https://api.github.com/repos/graalvm/truffle/contents/{+path}","compare_url":"https://api.github.com/repos/graalvm/truffle/compare/{base}...{head}","merges_url":"https://api.github.com/repos/graalvm/truffle/merges","archive_url":"https://api.github.com/repos/graalvm/truffle/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/graalvm/truffle/downloads","issues_url":"https://api.github.com/repos/graalvm/truffle/issues{/number}","pulls_url":"https://api.github.com/repos/graalvm/truffle/pulls{/number}","milestones_url":"https://api.github.com/repos/graalvm/truffle/milestones{/number}","notifications_url":"https://api.github.com/repos/graalvm/truffle/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/graalvm/truffle/labels{/name}","releases_url":"https://api.github.com/repos/graalvm/truffle/releases{/id}","deployments_url":"https://api.github.com/repos/graalvm/truffle/deployments","created_at":"2016-01-14T17:11:35Z","updated_at":"2016-02-09T20:45:29Z","pushed_at":"2016-02-10T13:00:45Z","git_url":"git://github.com/graalvm/truffle.git","ssh_url":"git@github.com:graalvm/truffle.git","clone_url":"https://github.com/graalvm/truffle.git","svn_url":"https://github.com/graalvm/truffle","homepage":"","size":20463,"stargazers_count":24,"watchers_count":24,"language":"Java","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":14,"mirror_url":null,"open_issues_count":9,"forks":14,"open_issues":9,"watchers":24,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/graalvm/truffle/pulls/1"},"html":{"href":"https://github.com/graalvm/truffle/pull/1"},"issue":{"href":"https://api.github.com/repos/graalvm/truffle/issues/1"},"comments":{"href":"https://api.github.com/repos/graalvm/truffle/issues/1/comments"},"review_comments":{"href":"https://api.github.com/repos/graalvm/truffle/pulls/1/comments"},"review_comment":{"href":"https://api.github.com/repos/graalvm/truffle/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/graalvm/truffle/pulls/1/commits"},"statuses":{"href":"https://api.github.com/repos/graalvm/truffle/statuses/c4cbc5097b1b86f0b6ca8e5ae3e8cd9b7015b1bc"}}}}