Provide source information to all dispatches and complement the API

Author: José Valim

lib/elixir/lib/module/dispatch_tracker.ex

@@ -48,24 +48,68 @@ defmodule Module.DispatchTracker do
   @timeout  30_000
   @behavior :gen_server
 
+  @type ref :: pid | module
+  @type name :: atom
+  @type name_arity :: { name, arity }
+
+  @type local :: { name, arity }
+  @type import :: { :import, name, arity }
+  @type remote :: { :remote, name, arity }
+
   # Public API
 
+  @doc """
+  Receives a dispatch or a module and returns all dispatches
+  that calls it.
+
+  In case the argument is a module, the response will be
+  made by import and remote dispatches.
+
+  In case the argument is another dispatch, the response
+  will be made by local dispatches.
+
+  This function is not recursive, so if A dispatches to
+  B which dispatches to C, A does not appear in the result,
+  only B.
+  """
+  @spec dispatches_to(ref, module) :: [import | remote]
+  @spec dispatches_to(ref, local | import | remote) :: [local]
+  def dispatches_to(ref, dispatch) do
+    d = :gen_server.call(to_pid(ref), :digraph, @timeout)
+    :digraph.in_neighbours(d, dispatch) |> only_tuples
+  end
+
+  @doc """
+  Receives a local and returns all dispatches from that local.
+
+  This function is not recursive, so if A dispatches to
+  B which dispatches to C, C does not appear in the result,
+  only B.
+  """
+  @spec dispatches_from(ref, local) :: [local | import | remote]
+  def dispatches_from(ref, { name, arity }) do
+    d = :gen_server.call(to_pid(ref), :digraph, @timeout)
+    :digraph.out_neighbours(d, { name, arity }) |> only_tuples
+  end
+
   @doc """
   Returns all the modules which were imported.
   All external dependencies to a module is the sum
   of imports and remotes.
   """
-  def imports(pid) do
-    d = :gen_server.call(to_pid(pid), :digraph, @timeout)
+  @spec imports(ref) :: [module]
+  def imports(ref) do
+    d = :gen_server.call(to_pid(ref), :digraph, @timeout)
     :digraph.out_neighbours(d, :import)
   end
 
   @doc """
   Returns all imported modules that had the given
   `{ name, arity }` invoked.
   """
-  def imports_with_dispatch(pid, { name, arity }) do
-    d = :gen_server.call(to_pid(pid), :digraph, @timeout)
+  @spec imports_with_dispatch(ref, name_arity) :: [module]
+  def imports_with_dispatch(ref, { name, arity }) do
+    d = :gen_server.call(to_pid(ref), :digraph, @timeout)
     :digraph.out_neighbours(d, { :import, name, arity })
   end
 
@@ -74,17 +118,19 @@ defmodule Module.DispatchTracker do
   to. All external dependencies to a module is the sum
   of imports and remotes.
   """
-  def remotes(pid) do
-    d = :gen_server.call(to_pid(pid), :digraph, @timeout)
+  @spec remotes(ref) :: [module]
+  def remotes(ref) do
+    d = :gen_server.call(to_pid(ref), :digraph, @timeout)
     :digraph.out_neighbours(d, :remote)
   end
 
   @doc """
   Returns all modules that had the given `{ name, arity }`
   invoked remotely.
   """
-  def remotes_with_dispatch(pid, { name, arity }) do
-    d = :gen_server.call(to_pid(pid), :digraph, @timeout)
+  @spec remotes_with_dispatch(ref, name_arity) :: [module]
+  def remotes_with_dispatch(ref, { name, arity }) do
+    d = :gen_server.call(to_pid(ref), :digraph, @timeout)
     :digraph.out_neighbours(d, { :remote, name, arity })
   end
 
@@ -95,8 +141,9 @@ defmodule Module.DispatchTracker do
   A private function is only reachable if it has
   a public function that it invokes directly.
   """
-  def reachable(pid) do
-    d = :gen_server.call(to_pid(pid), :digraph, @timeout)
+  @spec reachable(ref) :: [local]
+  def reachable(ref) do
+    d = :gen_server.call(to_pid(ref), :digraph, @timeout)
     reduce_reachable(d, :local, [])
   end
 
@@ -110,6 +157,10 @@ defmodule Module.DispatchTracker do
   defp to_pid(pid) when is_pid(pid),  do: pid
   defp to_pid(mod) when is_atom(mod), do: Module.get_attribute(mod, :__dispatch_tracker)
 
+  defp only_tuples(list) do
+    lc x inlist list, is_tuple(x), do: x
+  end
+
   # Internal API
 
   # Starts the tracker and returns its pid.
@@ -141,14 +192,14 @@ defmodule Module.DispatchTracker do
 
   # Adds a remote dispatch to the given target.
   @doc false
-  def add_remote(pid, module, target) when is_atom(module) and is_tuple(target) do
-    :gen_server.cast(pid, { :add_remote, module, target })
+  def add_remote(pid, function, module, target) when is_atom(module) and is_tuple(target) do
+    :gen_server.cast(pid, { :add_remote, function, module, target })
   end
 
   # Adds a import dispatch to the given target.
   @doc false
-  def add_import(pid, module, target) when is_atom(module) and is_tuple(target) do
-    :gen_server.cast(pid, { :add_import, module, target })
+  def add_import(pid, function, module, target) when is_atom(module) and is_tuple(target) do
+    :gen_server.cast(pid, { :add_import, function, module, target })
   end
 
   # Associates a module with a warn. This adds the given
@@ -280,13 +331,13 @@ defmodule Module.DispatchTracker do
     { :noreply, d }
   end
 
-  def handle_cast({ :add_remote, module, { name, arity } }, d) do
-    record_import_or_remote(d, :remote, module, name, arity)
+  def handle_cast({ :add_remote, function, module, { name, arity } }, d) do
+    record_import_or_remote(d, :remote, function, module, name, arity)
     { :noreply, d }
   end
 
-  def handle_cast({ :add_import, module, { name, arity } }, d) do
-    record_import_or_remote(d, :import, module, name, arity)
+  def handle_cast({ :add_import, function, module, { name, arity } }, d) do
+    record_import_or_remote(d, :import, function, module, name, arity)
     { :noreply, d }
   end
 
@@ -336,13 +387,17 @@ defmodule Module.DispatchTracker do
     { :ok, d }
   end
 
-  defp record_import_or_remote(d, kind, module, name, arity) do
+  defp record_import_or_remote(d, kind, function, module, name, arity) do
     :digraph.add_vertex(d, module)
     replace_edge!(d, kind, module)
 
     tuple = { kind, name, arity }
     :digraph.add_vertex(d, tuple)
     replace_edge!(d, tuple, module)
+
+    if function != nil do
+      replace_edge!(d, function, tuple)
+    end
   end
 
   defp replace_edge!(d, from, to) do

lib/elixir/src/elixir_def_local.erl

@@ -5,10 +5,10 @@
 
 macro_for(_Tuple, _All, #elixir_scope{module=nil}) -> false;
 
-macro_for(Tuple, All, #elixir_scope{module=Module} = S) ->
+macro_for(Tuple, All, #elixir_scope{module=Module,function=Function} = S) ->
   try elixir_def:lookup_definition(Module, Tuple) of
     { { Tuple, Kind, Line, _, _, _, _ }, Clauses } when Kind == defmacro; All, Kind == defmacrop ->
-      elixir_tracker:record_local(Tuple, S),
+      elixir_tracker:record_local(Tuple, Module, Function),
       get_function(Line, Module, Clauses);
     _ ->
       false

lib/elixir/src/elixir_dispatch.erl

@@ -34,14 +34,14 @@ import_function(Meta, Name, Arity, S) ->
   Tuple = { Name, Arity },
   case find_dispatch(Meta, Tuple, S) of
     { function, Receiver } ->
-      elixir_tracker:record_import(Tuple, Receiver, S#elixir_scope.module),
+      elixir_tracker:record_import(Tuple, Receiver, S#elixir_scope.module, S#elixir_scope.function),
       remote_function(Meta, Receiver, Name, Arity, S);
     { macro, _Receiver } ->
       false;
     { import, Receiver } ->
       require_function(Meta, Receiver, Name, Arity, S);
     nomatch ->
-      elixir_tracker:record_local(Tuple, S),
+      elixir_tracker:record_local(Tuple, S#elixir_scope.module, S#elixir_scope.function),
       { { 'fun', ?line(Meta), { function, Name, Arity } }, S }
   end.
 
@@ -51,7 +51,7 @@ require_function(Meta, Receiver, Name, Arity, S) ->
   case is_element(Tuple, get_optional_macros(Receiver)) of
     true  -> false;
     false ->
-      elixir_tracker:record_remote(Tuple, Receiver, S#elixir_scope.module),
+      elixir_tracker:record_remote(Tuple, Receiver, S#elixir_scope.module, S#elixir_scope.function),
       remote_function(Meta, Receiver, Name, Arity, S)
   end.
 
@@ -64,21 +64,21 @@ dispatch_import(Meta, Name, Args, S, Callback) ->
 
   case find_dispatch(Meta, Tuple, S) of
     { function, Receiver } ->
-      elixir_tracker:record_import(Tuple, Receiver, Module),
+      elixir_tracker:record_import(Tuple, Receiver, Module, S#elixir_scope.function),
       Endpoint = case (Receiver == ?builtin) andalso is_element(Tuple, in_erlang_functions()) of
         true  -> erlang;
         false -> Receiver
       end,
       elixir_translator:translate_each({ { '.', Meta, [Endpoint, Name] }, Meta, Args }, S);
     { import, Receiver } ->
-      elixir_tracker:record_remote(Tuple, Receiver, S#elixir_scope.module),
+      elixir_tracker:record_remote(Tuple, Receiver, S#elixir_scope.module, S#elixir_scope.function),
       elixir_translator:translate_each({ { '.', Meta, [Receiver, Name] }, [{require,false}|Meta], Args }, S);
     Result ->
       case do_expand_import(Meta, Tuple, Args, Module, S, Result) of
         { error, noexpansion } ->
           Callback();
         { error, internal } ->
-          elixir_tracker:record_import(Tuple, ?builtin, Module),
+          elixir_tracker:record_import(Tuple, ?builtin, Module, S#elixir_scope.function),
           elixir_macros:translate({ Name, Meta, Args }, S);
         { ok, _Receiver, Tree } ->
           translate_expansion(Meta, Tree, S)
@@ -92,15 +92,15 @@ dispatch_require(Meta, Receiver, Name, Args, S, Callback) ->
 
   case (Receiver == ?builtin) andalso is_element(Tuple, in_erlang_functions()) of
     true ->
-      elixir_tracker:record_remote(Tuple, Receiver, S#elixir_scope.module),
+      elixir_tracker:record_remote(Tuple, Receiver, S#elixir_scope.module, S#elixir_scope.function),
       { TArgs, SA } = elixir_translator:translate_args(Args, S),
       { ?wrap_call(?line(Meta), erlang, Name, TArgs), SA };
     false ->
       case expand_require(Meta, Receiver, Tuple, Args, Module, S) of
         { error, noexpansion } ->
           Callback();
         { error, internal } ->
-          elixir_tracker:record_remote(Tuple, ?builtin, S#elixir_scope.module),
+          elixir_tracker:record_remote(Tuple, ?builtin, S#elixir_scope.module, S#elixir_scope.function),
           elixir_macros:translate({ Name, Meta, Args }, S);
         { ok, _Receiver, Tree } ->
           translate_expansion(Meta, Tree, S)
@@ -119,11 +119,11 @@ do_expand_import(Meta, { Name, Arity } = Tuple, Args, Module, S, Result) ->
       case is_element(Tuple, in_erlang_macros()) of
         true  -> { error, internal };
         false ->
-          elixir_tracker:record_import(Tuple, ?builtin, Module),
+          elixir_tracker:record_import(Tuple, ?builtin, Module, S#elixir_scope.function),
           { ok, ?builtin, expand_macro_named(Meta, ?builtin, Name, Arity, Args, Module, S) }
       end;
     { macro, Receiver } ->
-      elixir_tracker:record_import(Tuple, Receiver, Module),
+      elixir_tracker:record_import(Tuple, Receiver, Module, S#elixir_scope.function),
       { ok, Receiver, expand_macro_named(Meta, Receiver, Name, Arity, Args, Module, S) };
     { import, Receiver } ->
       expand_require(Meta, Receiver, Tuple, Args, Module, S);
@@ -143,7 +143,7 @@ expand_require(Meta, ?builtin, { Name, Arity } = Tuple, Args, Module, S) ->
     false ->
       case is_element(Tuple, in_elixir_macros()) of
         true  ->
-          elixir_tracker:record_remote(Tuple, ?builtin, S#elixir_scope.module),
+          elixir_tracker:record_remote(Tuple, ?builtin, S#elixir_scope.module, S#elixir_scope.function),
           { ok, ?builtin, expand_macro_named(Meta, ?builtin, Name, Arity, Args, Module, S) };
         false ->
           { error, noexpansion }
@@ -158,7 +158,7 @@ expand_require(Meta, Receiver, { Name, Arity } = Tuple, Args, Module, S) ->
     false ->
       case is_element(Tuple, get_optional_macros(Receiver)) of
         true  ->
-          elixir_tracker:record_remote(Tuple, Receiver, S#elixir_scope.module),
+          elixir_tracker:record_remote(Tuple, Receiver, S#elixir_scope.module, S#elixir_scope.function),
           { ok, Receiver, expand_macro_named(Meta, Receiver, Name, Arity, Args, Module, S) };
         false -> { error, noexpansion }
       end;

lib/elixir/src/elixir_tracker.erl

@@ -3,7 +3,8 @@
 -module(elixir_tracker).
 -export([
   setup/1, cleanup/1,
-  record_local/2, record_import/3, record_remote/3,
+  record_local/2, record_local/3,
+  record_import/4, record_remote/4,
   record_warn/4, record_definition/3,
   ensure_no_import_conflict/4, ensure_all_imports_used/3,
   warn_unused_local/3, format_error/1
@@ -28,10 +29,10 @@ record_local(Tuple, Module) when is_atom(Module) ->
   if_tracker(Module, fun(Pid) ->
     ?tracker:add_local(Pid, Tuple),
     true
-  end);
-record_local(Tuple, #elixir_scope{function=Function})
+  end).
+record_local(Tuple, _Module, Function)
   when Function == nil; Function == Tuple -> false;
-record_local(Tuple, #elixir_scope{module=Module, function=Function}) ->
+record_local(Tuple, Module, Function) ->
   if_tracker(Module, fun(Pid) ->
     ?tracker:add_local(Pid, Function, Tuple),
     true
@@ -43,22 +44,22 @@ record_warn(Ref, Warn, Line, Module) ->
     true
   end).
 
-record_import(_Tuple, Receiver, Module)
+record_import(_Tuple, Receiver, Module, _Function)
   when Module == nil; Module == Receiver -> false;
-record_import(Tuple, Receiver, Module) ->
+record_import(Tuple, Receiver, Module, Function) ->
   try
     Pid = ets:lookup_element(Module, ?attr, 2),
-    ?tracker:add_import(Pid, Receiver, Tuple)
+    ?tracker:add_import(Pid, Function, Receiver, Tuple)
   catch
     error:badarg -> false
   end.
 
-record_remote(_Tuple, Receiver, Module)
+record_remote(_Tuple, Receiver, Module, _Function)
   when Module == nil; Module == Receiver -> false;
-record_remote(Tuple, Receiver, Module) ->
+record_remote(Tuple, Receiver, Module, Function) ->
   try
     Pid = ets:lookup_element(Module, ?attr, 2),
-    ?tracker:add_remote(Pid, Receiver, Tuple)
+    ?tracker:add_remote(Pid, Function, Receiver, Tuple)
   catch
     error:badarg -> false
   end.

lib/elixir/src/elixir_translator.erl

@@ -577,8 +577,8 @@ translate_fn(Meta, Clauses, S) ->
 
 %% Locals
 
-translate_local(Meta, Name, Args, #elixir_scope{local=nil} = S) ->
-  elixir_tracker:record_local({ Name, length(Args) }, S),
+translate_local(Meta, Name, Args, #elixir_scope{local=nil,module=Module,function=Function} = S) ->
+  elixir_tracker:record_local({ Name, length(Args) }, Module, Function),
   Line = ?line(Meta),
   { TArgs, NS } = translate_args(Args, S),
   { { call, Line, { atom, Line, Name }, TArgs }, NS };