From patchwork Mon Mar 7 17:16:03 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dodji Seketeli X-Patchwork-Id: 51751 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 4A44C3857805 for ; Mon, 7 Mar 2022 17:16:14 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 4A44C3857805 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1646673374; bh=npP5QoOgdZSCT1USi+JC85AkeukfHZY2GgfkgMwkLv8=; h=To:Subject:Date:List-Id:List-Unsubscribe:List-Archive:List-Help: List-Subscribe:From:Reply-To:From; b=X2sETLK5olVekVxTi5jALXAthb0Lm278ELxBh2dDIawnvUBCkcn9R+oI0BU/kOVVY dZsURr14HAcJ0pt63XVEFpQF9yVfeud7PeSlzF7J1UbbdhlGa4qiMoLr8pY3nhph1D 33o/wGgmG7+VhtDwex+RzfcueuTzlSnRujTSlz5A= X-Original-To: libabigail@sourceware.org Delivered-To: libabigail@sourceware.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id 4A4EC3858436 for ; Mon, 7 Mar 2022 17:16:09 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 4A4EC3858436 Received: from mail-qv1-f69.google.com (mail-qv1-f69.google.com [209.85.219.69]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-333-BS9X2sEOP8WZwcdGfb_HXQ-1; Mon, 07 Mar 2022 12:16:07 -0500 X-MC-Unique: BS9X2sEOP8WZwcdGfb_HXQ-1 Received: by mail-qv1-f69.google.com with SMTP id x16-20020a0ce250000000b00432ec6eaf85so13469571qvl.15 for ; Mon, 07 Mar 2022 09:16:07 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:subject:organization:date:message-id :user-agent:mime-version; bh=npP5QoOgdZSCT1USi+JC85AkeukfHZY2GgfkgMwkLv8=; b=wEGKAn5zzeOA1KaeHcFOjj9g4NAznWPfl7JwyF5Rb2WCxqX6CW4wlZqRtEm/bCZ7K8 eTVy2sjPAjXXaCbHMUOqizZfWgVP1XoKRJ1a8olvPE//VNSX3YZmuLQBTwsw/K7K2dUP KKiVtDXOm9MoyWFbaH2AEzhtuCq1T82lI1o4NT1ukd2QaTzdGWgBf9EoPpwgOOztjJOp Q9xqTtTCmwi9A/fqI4EajYG6P7hbTrPR+yDtg02RDvuORd13zX5l0FbdynWLDlslNjIt ZjpuBYYGjkkrpGqTKIcFEz/Miz20n77uk3uI444jykACfv6NTa4eYN9uk69dVI8joGzm 5cXw== X-Gm-Message-State: AOAM530swRbNK1dqv03dEpW7jLC4SI8jO18XV1T65Wk286BSBBjbd9lu jKsgqQDw5jzeC1xQH1KAhomTG3ZjEWXL1cDJ+Her6/kUo/PG4pKP+r7upiZ4TqnARHUe8B6lsMd gVM+BICpD7kxlwcm62rO19rswHGL3rfm6wUHz2f7+8uVWRy/MJZ2gZ4MGylaQJD5SaoOR X-Received: by 2002:a05:620a:318b:b0:663:2007:e20 with SMTP id bi11-20020a05620a318b00b0066320070e20mr7455883qkb.439.1646673366996; Mon, 07 Mar 2022 09:16:06 -0800 (PST) X-Google-Smtp-Source: ABdhPJy7+z679Q7OsSyNX3gV15eGD2186j103mi5fIgzPwmCIOJtsZZAN/mcz5RhxGQg8SekDNgS3Q== X-Received: by 2002:a05:620a:318b:b0:663:2007:e20 with SMTP id bi11-20020a05620a318b00b0066320070e20mr7455845qkb.439.1646673366380; Mon, 07 Mar 2022 09:16:06 -0800 (PST) Received: from localhost ([88.120.130.27]) by smtp.gmail.com with ESMTPSA id 15-20020ac8570f000000b002e05a1f990dsm4881865qtw.65.2022.03.07.09.16.05 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 07 Mar 2022 09:16:06 -0800 (PST) Received: by localhost (Postfix, from userid 1000) id 132BD581C3A; Mon, 7 Mar 2022 18:16:04 +0100 (CET) To: libabigail@sourceware.org Subject: [PATCH, applied] comparison: Describe the "generic view" of a diff node Organization: Red Hat / France X-Operating-System: Fedora 36 X-URL: http://www.redhat.com Date: Mon, 07 Mar 2022 18:16:03 +0100 Message-ID: <87zgm1heek.fsf@redhat.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-11.9 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H5, RCVD_IN_MSPIKE_WL, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-BeenThere: libabigail@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Mailing list of the Libabigail project List-Unsubscribe: , List-Archive: List-Help: List-Subscribe: , X-Patchwork-Original-From: Dodji Seketeli via Libabigail From: Dodji Seketeli Reply-To: Dodji Seketeli Errors-To: libabigail-bounces+patchwork=sourceware.org@sourceware.org Sender: "Libabigail" Hello, To add a node to the diff graph, what is used is the "generic view" (or generic API) of the diff node. To understand the difference between the generic view and the typed view of diff nodes, this patch adds comments to the diff node API. * include/abg-comparison.h (class diff): Add comments to this class. (diff::chain_into_hierarchy): Add comment to this method. * src/abg-comparison-priv.h (diff::priv): Add comment to this class. * src/abg-comparison.cc (diff::finish_diff_type): Add comment to this method. (diff::traverse): Add comment. Signed-off-by: Dodji Seketeli --- include/abg-comparison.h | 44 ++++++++++++++++++++++++++++++++++++++- src/abg-comparison-priv.h | 3 ++- src/abg-comparison.cc | 13 +++++++++++- 3 files changed, 57 insertions(+), 3 deletions(-) diff --git a/include/abg-comparison.h b/include/abg-comparison.h index 1350608a..595528a5 100644 --- a/include/abg-comparison.h +++ b/include/abg-comparison.h @@ -887,7 +887,44 @@ public: diff_context_sptr ctxt); };//end struct diff_context. -/// The abstraction of a change between two ABI artifacts. +/// The abstraction of a change between two ABI artifacts, a.k.a an +/// artifact change. +/// +/// In the grand scheme of things, a diff is strongly typed; for +/// instance, a change between two enums is represented by an +/// enum_diff type. A change between two function_type is represented +/// by a function_type_diff type and a change between two class_decl +/// is represented by a class_diff type. All of these types derive +/// from the @ref diff parent class. +/// +/// An artifact change D can have one (or more) details named D'. A +/// detail is an artifact change that "belongs" to another one. Here, +/// D' belongs to D. Or said otherwise, D' is a child change of D. +/// Said otherwise, D and D' are related, and the relation is a +/// "child relation". +/// +/// For instance, if we consider a change carried by a class_diff, the +/// detail change might be a change on one data member of the class. +/// In other word, the class_diff change might have a child diff node +/// that would be a var_diff node. +/// +/// There are two ways to get the child var_diff node (for the data +/// member change detail) of the class_diff. +/// +/// The first way is through the typed API, that is, through the +/// class_diff::sorted_changed_data_members() member function which +/// returns var_diff nodes. +/// +/// The second way is through the generic API, that is, through the +/// diff::children_nodes() member function which returns generic diff +/// nodes. This second way enables us to walk the diff nodes graph in +/// a generic way, regardless of the types of the diff nodes. +/// +/// Said otherwise, there are two views for a given diff node. There +/// is typed view, and there is the generic view. In the typed view, +/// the details are accessed through the typed API. In the generic +/// view, the details are gathered through the generic view. +/// /// /// Please read more about the @ref DiffNode "IR" of the comparison /// engine to learn more about this. @@ -1015,6 +1052,11 @@ public: virtual const string& get_pretty_representation() const; + /// This constructs the relation between this diff node and its + /// detail diff nodes, in the generic view of the diff node. + /// + /// Each specific typed diff node should implement how the typed + /// view "links" itself to its detail nodes in the generic sense. virtual void chain_into_hierarchy(); diff --git a/src/abg-comparison-priv.h b/src/abg-comparison-priv.h index 8e2e59c6..ef271d8b 100644 --- a/src/abg-comparison-priv.h +++ b/src/abg-comparison-priv.h @@ -240,7 +240,8 @@ public: friend class type_diff_base; }; // end class type_diff_base -/// Private data for the @ref diff type. +/// Private data for the @ref diff type. The details of generic view +/// of the diff node are expressed here. struct diff::priv { bool finished_; diff --git a/src/abg-comparison.cc b/src/abg-comparison.cc index 71048ce2..cc5b9f6d 100644 --- a/src/abg-comparison.cc +++ b/src/abg-comparison.cc @@ -1917,7 +1917,10 @@ diff::end_traversing() priv_->traversing_ = false; } -/// Finish the building of a given kind of a diff tree node. +/// Finish the insertion of a diff tree node into the diff graph. +/// +/// This function might be called several times. It must perform the +/// insertion only once. /// /// For instance, certain kinds of diff tree node have specific /// children nodes that are populated after the constructor of the @@ -2065,6 +2068,13 @@ diff::reported_once() const /// without traversing it. But traversing a node without visiting it /// is not possible. /// +/// Note that the insertion of the "generic view" of the diff node +/// into the graph being traversed is done "on the fly". The +/// insertion of the "typed view" of the diff node into the graph is +/// done implicitely. To learn more about the generic and typed view +/// of the diff node, please read the introductory comments of the +/// @ref diff class. +/// /// Note that by default this traversing code visits a given class of /// equivalence of a diff node only once. This behaviour can been /// changed by calling @@ -2102,6 +2112,7 @@ diff::reported_once() const bool diff::traverse(diff_node_visitor& v) { + // Insert the "generic view" of the diff node into its graph. finish_diff_type(); v.visit_begin(this);