libabigail
Classes | Public Types | Public Member Functions | Protected Member Functions | Friends | List of all members
corpus_diff Class Reference

An abstraction of a diff between between two abi corpus. More...

#include <abg-comparison.h>

Classes

class  diff_stats
 This is a document class that aims to capture statistics about the changes carried by a corpus_diff type. More...
 
struct  priv
 

Public Types

typedef shared_ptr< diff_statsdiff_stats_sptr
 A convenience typedef for a shared pointer to diff_stats. More...
 

Public Member Functions

const string_function_ptr_mapadded_functions ()
 Getter for the added functions of the diff. More...
 
const string_type_base_sptr_mapadded_unreachable_types () const
 Getter for a map of added types that are not reachable from global functions/variables. More...
 
const vector< type_base_sptr > & added_unreachable_types_sorted () const
 Getter of a sorted vector of added types that are not reachable from global functions/variables. More...
 
const string_elf_symbol_mapadded_unrefed_function_symbols () const
 Getter for function symbols not referenced by any debug info and that got added. More...
 
const string_elf_symbol_mapadded_unrefed_variable_symbols () const
 Getter for variable symbols not referenced by any debug info and that got added. More...
 
const string_var_ptr_mapadded_variables () const
 Getter for the added variables of the diff. More...
 
void append_child_node (diff_sptr)
 Append a new child node to the vector of children nodes for the current instance of corpus_diff node. More...
 
const diff_statsapply_filters_and_suppressions_before_reporting ()
 Apply the different filters that are registered to be applied to the diff tree; that includes the categorization filters. Also, apply the suppression interpretation filters. More...
 
bool architecture_changed () const
 Test if the architecture of the underlying corpus has changed. More...
 
virtual void chain_into_hierarchy ()
 Populate the vector of children node of the corpus_diff type. More...
 
const string_function_decl_diff_sptr_mapchanged_functions ()
 Getter for the functions which signature didn't change, but which do have some indirect changes in their parms. More...
 
const function_decl_diff_sptrs_typechanged_functions_sorted ()
 Getter for a sorted vector of functions which signature didn't change, but which do have some indirect changes in their parms. More...
 
const string_diff_sptr_mapchanged_unreachable_types () const
 Getter for a map of changed types that are not reachable from global functions/variables. More...
 
const vector< diff_sptr > & changed_unreachable_types_sorted () const
 Getter of a sorted vector of changed types that are not reachable from global functions/variables. More...
 
const string_var_diff_sptr_mapchanged_variables ()
 Getter for the non-sorted map of variables which signature didn't change but which do have some indirect changes in some sub-types. More...
 
const var_diff_sptrs_typechanged_variables_sorted ()
 Getter for the sorted vector of variables which signature didn't change but which do have some indirect changes in some sub-types. More...
 
const vector< diff * > & children_nodes () const
 
const diff_context_sptr context () const
 Getter of the diff context of this diff. More...
 
const string_function_ptr_mapdeleted_functions () const
 Getter for the deleted functions of the diff. More...
 
const string_type_base_sptr_mapdeleted_unreachable_types () const
 Getter for a map of deleted types that are not reachable from global functions/variables. More...
 
const vector< type_base_sptr > & deleted_unreachable_types_sorted () const
 Getter of a sorted vector of deleted types that are not reachable from global functions/variables. More...
 
const string_elf_symbol_mapdeleted_unrefed_function_symbols () const
 Getter for function symbols not referenced by any debug info and that got deleted. More...
 
const string_elf_symbol_mapdeleted_unrefed_variable_symbols () const
 Getter for variable symbols not referenced by any debug info and that got deleted. More...
 
const string_var_ptr_mapdeleted_variables () const
 Getter for the variables that got deleted from the first subject of the diff. More...
 
bool do_log () const
 Test if logging was requested. More...
 
void do_log (bool)
 Request logging, or not. More...
 
corpus_sptr first_corpus () const
 
edit_scriptfunction_changes () const
 
diff_mapsget_leaf_diffs ()
 Get the set of maps that contain leaf nodes. A leaf node being a node with a local change. More...
 
const diff_mapsget_leaf_diffs () const
 Get the set of maps that contain leaf nodes. A leaf node being a node with a local change. More...
 
const string & get_pretty_representation () const
 
bool has_changes () const
 Return true iff the current corpus_diff node carries a change. More...
 
bool has_incompatible_changes () const
 Test if the current instance of corpus_diff carries changes that we are sure are incompatible. By incompatible change we mean a change that "breaks" the ABI of the corpus we are looking at. More...
 
bool has_net_changes () const
 Test if the current instance of corpus_diff carries changes whose reports are not suppressed by any suppression specification. In effect, these are deemed incompatible ABI changes. More...
 
bool has_net_subtype_changes () const
 Test if the current instance of corpus_diff carries subtype changes whose reports are not suppressed by any suppression specification. In effect, these are deemed incompatible ABI changes. More...
 
void mark_leaf_diff_nodes ()
 Walks the diff nodes associated to the current corpus diff and mark those that carry local changes. They are said to be leaf diff nodes. More...
 
virtual void report (ostream &out, const string &indent="") const
 Report the diff in a serialized form. More...
 
corpus_sptr second_corpus () const
 
bool soname_changed () const
 Test if the soname of the underlying corpus has changed. More...
 
virtual bool traverse (diff_node_visitor &v)
 Traverse the diff sub-tree under the current instance corpus_diff. More...
 
edit_scriptvariable_changes () const
 

Protected Member Functions

 corpus_diff (corpus_sptr first, corpus_sptr second, diff_context_sptr ctxt=diff_context_sptr())
 Constructor for corpus_diff. More...
 
void finish_diff_type ()
 Finish building the current instance of corpus_diff. More...
 

Friends

void apply_suppressions (const corpus_diff *diff_tree)
 Walk a corpus_diff tree and appply the suppressions carried by the context. If the suppression applies to a given node then categorize the node into the SUPPRESSED_CATEGORY category and propagate that categorization. More...
 
corpus_diff_sptr compute_diff (const corpus_sptr f, const corpus_sptr s, diff_context_sptr ctxt)
 Compute the diff between two instances of corpus. More...
 
class default_reporter
 
class leaf_reporter
 
void maybe_report_unreachable_type_changes (const corpus_diff &d, const corpus_diff::diff_stats &s, const string &indent, ostream &out)
 Report changes about types that are not reachable from global functions and variables, in a given. More...
 

Detailed Description

An abstraction of a diff between between two abi corpus.

Definition at line 2400 of file abg-comparison.h.

Member Typedef Documentation

◆ diff_stats_sptr

typedef shared_ptr<diff_stats> diff_stats_sptr

A convenience typedef for a shared pointer to diff_stats.

Definition at line 2420 of file abg-comparison.h.

Constructor & Destructor Documentation

◆ corpus_diff()

corpus_diff ( corpus_sptr  first,
corpus_sptr  second,
diff_context_sptr  ctxt = diff_context_sptr() 
)
protected

Constructor for corpus_diff.

Parameters
firstthe first corpus of the diff.
secondthe second corpus of the diff.
ctxtthe diff context to use. Note that this context object must stay alive at least during the life time of the current instance of corpus_diff. Otherwise memory corruption issues occur.

Definition at line 10994 of file abg-comparison.cc.

Member Function Documentation

◆ added_functions()

const string_function_ptr_map & added_functions ( )

Getter for the added functions of the diff.

Returns
the added functions of the diff.

Definition at line 11119 of file abg-comparison.cc.

◆ added_unreachable_types()

const string_type_base_sptr_map & added_unreachable_types ( ) const

Getter for a map of added types that are not reachable from global functions/variables.

Returns
a map that associates pretty representation of added unreachable types and said types.

Definition at line 11242 of file abg-comparison.cc.

◆ added_unreachable_types_sorted()

const vector< type_base_sptr > & added_unreachable_types_sorted ( ) const

Getter of a sorted vector of added types that are not reachable from global functions/variables.

Returns
a sorted vector of added types that are not reachable from global functions/variables. The types are lexicographically sorted by considering their pretty representation.

Definition at line 11252 of file abg-comparison.cc.

◆ added_unrefed_function_symbols()

const string_elf_symbol_map & added_unrefed_function_symbols ( ) const

Getter for function symbols not referenced by any debug info and that got added.

Returns
a map of elf function symbols not referenced by any debug info and that got added.

Definition at line 11189 of file abg-comparison.cc.

◆ added_unrefed_variable_symbols()

const string_elf_symbol_map & added_unrefed_variable_symbols ( ) const

Getter for variable symbols not referenced by any debug info and that got added.

Returns
a map of elf variable symbols not referenced by any debug info and that got added.

Definition at line 11207 of file abg-comparison.cc.

◆ added_variables()

const string_var_ptr_map & added_variables ( ) const

Getter for the added variables of the diff.

Returns
the map of added variable.

Definition at line 11155 of file abg-comparison.cc.

◆ append_child_node()

void append_child_node ( diff_sptr  d)

Append a new child node to the vector of children nodes for the current instance of corpus_diff node.

Note that the vector of children nodes for the current instance of corpus_diff node must remain sorted, using diff_less_than_functor.

Parameters
dthe new child node. Note that the life time of the object held by d will thus equal the life time of the current instance of corpus_diff.

Definition at line 11052 of file abg-comparison.cc.

◆ apply_filters_and_suppressions_before_reporting()

const corpus_diff::diff_stats & apply_filters_and_suppressions_before_reporting ( )

Apply the different filters that are registered to be applied to the diff tree; that includes the categorization filters. Also, apply the suppression interpretation filters.

After the filters are applied, this function calculates some statistics about the changes carried by the current instance of corpus_diff. These statistics are represented by an instance of corpus_diff::diff_stats.

This member function is called by the reporting function corpus_diff::report().

Note that for a given instance of corpus_diff, this function applies the filters and suppressions only the first time it is invoked. Subsequent invocations just return the instance of corpus_diff::diff_stats that was cached after the first invocation.

Returns
a reference to the statistics about the changes carried by the current instance of corpus_diff.

Definition at line 11448 of file abg-comparison.cc.

◆ architecture_changed()

bool architecture_changed ( ) const

Test if the architecture of the underlying corpus has changed.

Returns
true iff the architecture has changed.

Definition at line 11105 of file abg-comparison.cc.

◆ chain_into_hierarchy()

void chain_into_hierarchy ( )
virtual

Populate the vector of children node of the corpus_diff type.

The children node can then later be retrieved using corpus_diff::children_node().

Definition at line 10974 of file abg-comparison.cc.

◆ changed_functions()

const string_function_decl_diff_sptr_map & changed_functions ( )

Getter for the functions which signature didn't change, but which do have some indirect changes in their parms.

Returns
a non-sorted map of functions which signature didn't change, but which do have some indirect changes in their parms. The key of the map is a unique identifier for the function; it's usually made of the name and version of the underlying ELF symbol of the function for corpora that were built from ELF files.

Definition at line 11131 of file abg-comparison.cc.

◆ changed_functions_sorted()

const function_decl_diff_sptrs_type & changed_functions_sorted ( )

Getter for a sorted vector of functions which signature didn't change, but which do have some indirect changes in their parms.

Returns
a sorted vector of functions which signature didn't change, but which do have some indirect changes in their parms.

Definition at line 11140 of file abg-comparison.cc.

◆ changed_unreachable_types()

const string_diff_sptr_map & changed_unreachable_types ( ) const

Getter for a map of changed types that are not reachable from global functions/variables.

Returns
a map that associates pretty representation of changed unreachable types and said types.

Definition at line 11268 of file abg-comparison.cc.

◆ changed_unreachable_types_sorted()

const vector< diff_sptr > & changed_unreachable_types_sorted ( ) const

Getter of a sorted vector of changed types that are not reachable from global functions/variables.

Returns
a sorted vector of changed types that are not reachable from global functions/variables. The diffs are lexicographically sorted by considering their pretty representation.

Definition at line 11278 of file abg-comparison.cc.

◆ changed_variables()

const string_var_diff_sptr_map & changed_variables ( )

Getter for the non-sorted map of variables which signature didn't change but which do have some indirect changes in some sub-types.

Returns
the non-sorted map of changed variables.

Definition at line 11163 of file abg-comparison.cc.

◆ changed_variables_sorted()

const var_diff_sptrs_type & changed_variables_sorted ( )

Getter for the sorted vector of variables which signature didn't change but which do have some indirect changes in some sub-types.

Returns
a sorted vector of changed variables.

Definition at line 11171 of file abg-comparison.cc.

◆ children_nodes()

const vector< diff * > & children_nodes ( ) const
Returns
the children nodes of the current instance of corpus_diff.

Definition at line 11038 of file abg-comparison.cc.

◆ context()

const diff_context_sptr context ( ) const

Getter of the diff context of this diff.

Returns
the diff context for this diff.

Definition at line 11285 of file abg-comparison.cc.

◆ deleted_functions()

const string_function_ptr_map & deleted_functions ( ) const

Getter for the deleted functions of the diff.

Returns
the the deleted functions of the diff.

Definition at line 11112 of file abg-comparison.cc.

◆ deleted_unreachable_types()

const string_type_base_sptr_map & deleted_unreachable_types ( ) const

Getter for a map of deleted types that are not reachable from global functions/variables.

Returns
a map that associates pretty representation of deleted unreachable types and said types.

Definition at line 11216 of file abg-comparison.cc.

◆ deleted_unreachable_types_sorted()

const vector< type_base_sptr > & deleted_unreachable_types_sorted ( ) const

Getter of a sorted vector of deleted types that are not reachable from global functions/variables.

Returns
a sorted vector of deleted types that are not reachable from global functions/variables. The types are lexicographically sorted by considering their pretty representation.

Definition at line 11226 of file abg-comparison.cc.

◆ deleted_unrefed_function_symbols()

const string_elf_symbol_map & deleted_unrefed_function_symbols ( ) const

Getter for function symbols not referenced by any debug info and that got deleted.

Returns
a map of elf function symbols not referenced by any debug info and that got deleted.

Definition at line 11180 of file abg-comparison.cc.

◆ deleted_unrefed_variable_symbols()

const string_elf_symbol_map & deleted_unrefed_variable_symbols ( ) const

Getter for variable symbols not referenced by any debug info and that got deleted.

Returns
a map of elf variable symbols not referenced by any debug info and that got deleted.

Definition at line 11198 of file abg-comparison.cc.

◆ deleted_variables()

const string_var_ptr_map & deleted_variables ( ) const

Getter for the variables that got deleted from the first subject of the diff.

Returns
the map of deleted variable.

Definition at line 11148 of file abg-comparison.cc.

◆ do_log() [1/2]

bool do_log ( ) const

Test if logging was requested.

Returns
true iff logging was requested.

Definition at line 11016 of file abg-comparison.cc.

◆ do_log() [2/2]

void do_log ( bool  f)

Request logging, or not.

Parameters
ftrue iff logging is requested.

Definition at line 11023 of file abg-comparison.cc.

◆ finish_diff_type()

void finish_diff_type ( )
protected

Finish building the current instance of corpus_diff.

Definition at line 11004 of file abg-comparison.cc.

◆ first_corpus()

corpus_sptr first_corpus ( ) const
Returns
the first corpus of the diff.

Definition at line 11028 of file abg-comparison.cc.

◆ function_changes()

edit_script & function_changes ( ) const
Returns
the bare edit script of the functions changed as recorded by the diff.

Definition at line 11085 of file abg-comparison.cc.

◆ get_leaf_diffs() [1/2]

diff_maps & get_leaf_diffs ( )

Get the set of maps that contain leaf nodes. A leaf node being a node with a local change.

Returns
the set of maps that contain leaf nodes. A leaf node being a node with a local change.

Definition at line 11609 of file abg-comparison.cc.

◆ get_leaf_diffs() [2/2]

const diff_maps & get_leaf_diffs ( ) const

Get the set of maps that contain leaf nodes. A leaf node being a node with a local change.

Returns
the set of maps that contain leaf nodes. A leaf node being a node with a local change.

Definition at line 11618 of file abg-comparison.cc.

◆ get_pretty_representation()

const string & get_pretty_representation ( ) const
Returns
the pretty representation for the current instance of corpus_diff

Definition at line 11291 of file abg-comparison.cc.

◆ has_changes()

bool has_changes ( ) const

Return true iff the current corpus_diff node carries a change.

Returns
true iff the current diff node carries a change.

Definition at line 11310 of file abg-comparison.cc.

◆ has_incompatible_changes()

bool has_incompatible_changes ( ) const

Test if the current instance of corpus_diff carries changes that we are sure are incompatible. By incompatible change we mean a change that "breaks" the ABI of the corpus we are looking at.

In concrete terms, this function considers the following changes as being ABI incompatible for sure:

  • a soname change
  • if exported functions or variables got removed

Note that subtype changes *can* represent changes that break ABI too. But they also can be changes that are OK, ABI-wise.

It's up to the user to provide suppression specifications to say explicitely which subtype change is OK. The remaining sub-type changes are then considered to be ABI incompatible. But to test if such ABI incompatible subtype changes are present you need to use the function corpus_diff::has_net_subtype_changes()

Returns
true iff the current instance of corpus_diff carries changes that we are sure are ABI incompatible.

Definition at line 11351 of file abg-comparison.cc.

◆ has_net_changes()

bool has_net_changes ( ) const

Test if the current instance of corpus_diff carries changes whose reports are not suppressed by any suppression specification. In effect, these are deemed incompatible ABI changes.

Returns
true iff the the current instance of corpus_diff carries subtype changes that are deemed incompatible ABI changes.

Definition at line 11424 of file abg-comparison.cc.

◆ has_net_subtype_changes()

bool has_net_subtype_changes ( ) const

Test if the current instance of corpus_diff carries subtype changes whose reports are not suppressed by any suppression specification. In effect, these are deemed incompatible ABI changes.

Returns
true iff the the current instance of corpus_diff carries subtype changes that are deemed incompatible ABI changes.

Definition at line 11406 of file abg-comparison.cc.

◆ mark_leaf_diff_nodes()

void mark_leaf_diff_nodes ( )

Walks the diff nodes associated to the current corpus diff and mark those that carry local changes. They are said to be leaf diff nodes.

The marked nodes are available from the corpus_diff::get_leaf_diffs() function.

Definition at line 11584 of file abg-comparison.cc.

◆ report()

void report ( ostream &  out,
const string &  indent = "" 
) const
virtual

Report the diff in a serialized form.

Parameters
outthe stream to serialize the diff to.
indentthe prefix to use for the indentation of this serialization.

Definition at line 11628 of file abg-comparison.cc.

◆ second_corpus()

corpus_sptr second_corpus ( ) const
Returns
the second corpus of the diff.

Definition at line 11033 of file abg-comparison.cc.

◆ soname_changed()

bool soname_changed ( ) const

Test if the soname of the underlying corpus has changed.

Returns
true iff the soname has changed.

Definition at line 11098 of file abg-comparison.cc.

◆ traverse()

bool traverse ( diff_node_visitor v)
virtual

Traverse the diff sub-tree under the current instance corpus_diff.

Parameters
vthe visitor to invoke on each diff node of the sub-tree.
Returns
true if the traversing has to keep going on, false otherwise.

Definition at line 11639 of file abg-comparison.cc.

◆ variable_changes()

edit_script & variable_changes ( ) const
Returns
the bare edit script of the variables changed as recorded by the diff.

Definition at line 11091 of file abg-comparison.cc.

Friends And Related Function Documentation

◆ apply_suppressions

void apply_suppressions ( const corpus_diff diff_tree)
friend

Walk a corpus_diff tree and appply the suppressions carried by the context. If the suppression applies to a given node then categorize the node into the SUPPRESSED_CATEGORY category and propagate that categorization.

Parameters
diff_treethe diff tree to apply the suppressions to.

Definition at line 12555 of file abg-comparison.cc.

◆ compute_diff

corpus_diff_sptr compute_diff ( const corpus_sptr  f,
const corpus_sptr  s,
diff_context_sptr  ctxt 
)
friend

Compute the diff between two instances of corpus.

Note that the two corpora must have been created in the same environment, otherwise, this function aborts.

Parameters
fthe first corpus to consider for the diff.
sthe second corpus to consider for the diff.
ctxtthe diff context to use.
Returns
the resulting diff between the two corpus.

Definition at line 11735 of file abg-comparison.cc.

◆ maybe_report_unreachable_type_changes

void maybe_report_unreachable_type_changes ( const corpus_diff d,
const corpus_diff::diff_stats s,
const string &  indent,
ostream &  out 
)
friend

Report changes about types that are not reachable from global functions and variables, in a given.

Parameters
corpus_diff.
dthe corpus_diff to consider.
sthe statistics of the changes, after filters and suppressions are reported. This is typically what is returned by corpus_diff::apply_filters_and_suppressions_before_reporting().
indentthe indendation string (usually a string of white spaces) to use for indentation during the reporting.
outthe output stream to emit the report to.

Definition at line 1350 of file abg-reporter-priv.cc.


The documentation for this class was generated from the following files: