Module and Function Dependencies

Concerning terminology

We say that a module A is dependent on another module B (A -> B) if there is at least one function call from A to B.
A cyclic dependency appears, when B is also dependent directly (B -> A) or indirectly (e.g. B -> C -> A) from A.

If one wants to have a deeper analysis and pays more attention to the concerning functions, a function level query should be done.
In our previous example, no function level cycle appears, unless A:foo calls B:foo, and B:foo calls A:foo.

Note that it is possible to have a cyclic dependency among the modules while having no cyclic dependencies among the functions.
For example, a function call from A:foo to B:foo, and from B:foo2 to A:foo2 implies a cyclic dependency on the module level.

Possible Analysis

There are different kind of examinations that can be run considering dependencies.

First of all, the possibility of checking for cycles on RefactorErl? database. This means that the program is going to look for loops on the given level, and returns with the path of the cycles.

If one wants to have a more visual view of the dependencies, there is the draw option. This will generate a .dot file, which latter can be converted to a desired image file format. Since in the case of a vast database, the generated picture of dependencies can be very complex and hard to figure out, there are different options how the user can narrow down the result, and get a more easier understandable view. For instance, it is possible just to receive an image of the graph which contains only the cycles, or to exclude the OTP modules from the result.
In every dependency option there is the opportunity to run the examination from a given function/module or a list of them.

Dependency analysis can be done through two interfaces:

1. ri (using RefactorErl? through console interface)
2. using the web interface. (see: wiki:WebInterface/DependencyExaminations)
   

The ri

The two interface functions are:

1. ri:draw_dep/1
   

   • for drawing

2. ri:print_dep/1
   

   • for listing, printing out to the standard output
     

To call the desired query, the user should give a proplist, stating the different requirements.

The options and the keys for the functions are:

*

{level, Level}
    Level = mod | func

Stating the level of the query, module or function level.

*

{type, Type}
     Type = all | cycles

The investigation should be done on the whole graph/table, or just on the cycle part (if it exists).
When listing out the cycles, all gives back the result in their graph node form, while cycles returns with their proper names.

*

{gnode, Node | lists(Node)}
    Node = node() | Name
    Name = Module::atom() | Function::string()

Specify a node or nodes (given in a list) as a starting point for the analysis.

• Module level: the name as an atom
  
• Function level: name as string ("Module:Function/Arity").
  
• In both cases the node/nodes can be given as graph nodes as well.
  

*

{dot, Dot::string()}

The user can stipulate his own name and absolute path or the generated .dot file. Unless it is a new absolute path, the .dot file will be placed into the ./dep_files directory. Only available in the case of draw_dep.

*

{exception, NodeList::lists(Node)}
     Node = node() | Name
     Name = Module::atom() | Function::string()

The exception key gives the user the opportunity to define certain nodes (by stating their name or by giving a gnode) which will be exluded from the analysis.

*

{leaves, NodeList::lists(Node)}
     Node = node() | Name
     Name = Module::atom() | Function::string()

Leaves contains those nodes which would be included in the analysis, but their children won't (so this way they become exceptions).

*

{otp, true | false}

The built-in erlang otp modules should be included in the analysis or not. The default value is false.

Examples for listing results

• Checking for cycles in module level.
  ri:print_dep([{level, mod}, {type, all}]).

• Checking for cycles in function level, and printing out the whole names of the functions (Module:Function/Arity).
  ri:print_dep([{level, func}, {type, cycles}]).

{6 cycle(s),
[['foo:fv4/1','foo:fv4/1'],
['test3:p/1','test:fv6/1','test3:p/1'],
['cycle4:f4/1','cycle3:f3/1','cycle4:f4/1'],
['cycle2:fv2/1','cycle1:fv1/0','cycle2:fv2/1'],
['test:fv5/1','test:fv4/2','test:fv5/1'],
['cycle4:f5/1','cycle3:f6/1','cycle4:f5/1']]

• Checking for cycles in function level, and printing out the graph nodes of the functions (notice the changed "type" in the proplist)
  ri:print_dep([{level, func}, {type, all}]).

{"6 cycle(s)",

[[{'$gn',func,28},{'$gn',func,28}],
[{'$gn',func,29},{'$gn',func,37},{'$gn',func,29}],
[{'$gn',func,7},{'$gn',func,9},{'$gn',func,7}],
[{'$gn',func,2},{'$gn',func,1},{'$gn',func,2}],
[{'$gn',func,36},{'$gn',func,35},{'$gn',func,36}],
[{'$gn',func,8},{'$gn',func,6},{'$gn',func,8}]]}

• Checking for cycles in module level from an exact node
  ri:print_dep([{level, mod}, {gnode, {'$gn', module, 24}}]).

{true,[[{'$gn',module,24},
{'$gn',module,25},
{'$gn',module,24}]]}

• Checking for cycles in function level from an exact node given with its whole name
  ri:print_dep([{level, func}, {gnode, "cycle4:f5/1"}]).

Representation

Function Level

Let's take an example to explain the meaning of the representation of dependency graphs. A ri:draw_dep([{level, func}, {type, all}]) call was made, which generated a Graphviz dot file.

Explanation of the figure:

• ROOT triangle - no actual purpose, functioning as a starting point, only appears in the representation
• Rectangle/box nodes (eg.: cycle1, a, test2) - representing modules (colour: deep purple)
• Hexagon nodes (eg.: f1/1, apply/3, test2/2) - representing functions (colour: black)
• Double octagon nodes - representing opaque nodes (colour: black, label colour: gray)
• Solid, continuous edge, normal arrowhead - normal edge indicating the modules from the root, and the

modules and their definitions of functions (colour: black)

• Dashed edge, normal arrowhead - indicates that a function calls another function (funcall) (colour: black)
• Dashed edge, special arrowhead - indicated a function call, but also that it is a cyclic edge (colour: red)

The next figure was made after a ri:anal_dyn() was run, which is a dynamic analyser. Due to its work the call graph changes a bit, new types of nodes and edges are introduced.

Explanation of figure, new nodes, edges:

• Double octagon nodes - representing opaque, -1 arity nodes (colour: black, label colour: gray)
• Dotted edge, normal arrowhead - indicates an ambcall, dyncall, may_be edge (colour: black)

Every node and edge have tooltips. In the case of nodes it shows the adequate graph node, while considering edges it depicts the type of function call (funcall, may_be, ambcall, dyncall). Static calls are labelled by funcall.

Dyncall means unambiguous dynamic calls, when the identifiers of the callee may be defined not at the call but at another program part, and their values are can be calculated by data-flow reaching. Ambcall relation denotes the fact that some of the arguments of the dynamic function call can not be detected statically. If the number of parameters is uncertain, then after the arity of the function will be -1. It is also indicated with a special node. For further details about the dynamic calls and their representation can be found in (wiki:DynamicCallAnalysis). When the applied function or module is uncertain, the tool represents it with an opaque node, and connects the possible functions/modules with may_be edges. The representation in the analysis now follows this, indicating the opaque nodes differently (described in the previous section, concerning drawings).

We note here that tooltips may not be shown under certain browsers (for example Mozilla Firefox 7.0.1). If this happens, please try another browser.

Module Level

Similarly, at module level, after calling ri:draw_dep([{level, mod}, {type, all}]), an analogous figure can be achieved.

Explanation of figure:

• Rectangle/box nodes (eg.: cycle1, erlang, test2) - representing modules (colour: deep purple)
• Doubleoctagon nodes (no example on the figure) - representing opaque nodes (colour: black, label colour: gray)
• Dotted edge, normal arrowhead - indicates that a module calls another module (colour: black)
• Dotted edge, special arrowhead - indicated a module call, but also that it is a cyclic edge (colour: red)

The tooltip for edges shows a list the function pair:
Call = {callee, called}, Tooltip = [] | [Call | Tooltip]
Latter makes a connection between the modules with this call.

Examples for the representation of the results

• ri:draw_dep([{level, mod}, {gnode, erlang}]).
• ri:draw_dep([{level, mod}, {gnode, erlang}, {dot, "/home/working/dot/test.dot" }]).
• ri:draw_dep([{level, func}, {gnode, "lists:hd/1"}]).
• ri:draw_dep([{level, mod},{gnode, {'$gn', module, 4}}]).
• ri:draw_dep([{type, cycles}, {level, func}, {gnode, {'$gn', func, 36}}]).