how are connections established?

[Eddie Kohler]

Hi Elaine,

> I am trying to find out how Click does the communication between elements
> so that I can compare it to a programming model I'm working on (see below
> for links).

Cool, sounds interesting.

> I have found sample code for elements in which an element's push() method
> calls the push() method of its output port.  Where can I find the code (or
> section of the runtime system) that connects the output port push() method
> with the input port of the connected element?  Does the output port push()
> method call the connected element's push() method, or does the output port
> push() method call a method on the connected element's input port, which
> in turn calls the connected element's push() method?

So the Element::Port::push() method looks like this (#ifdefs removed):

  inline void
  Element::Port::push(Packet *p) const
  {
    assert(_e);
    _e->push(_port, p);
  }

So pretty simple. The Port object just holds a pointer to the element
connected to that port (and the relevant port number on that element). (In
your terms, "the output port push() method call[s] the connected element's
push() method".) Code in include/click/element.hh.

> I am interested in finding out what parts of the code establishes all of
> the connections between elements during initialization (userlevel is
> fine),

Connection initialization is one of the more complex parts of Click. 

The Lexer object parses a configuration file and stores the resulting
connections in a Router object. At this point, the connections are simply
stored in a list of (from-element, from-port#, to-element, to-port#)
tuples. These are analyzed, and stored in actual element structures, during
Router initialization.

Each push or pull packet transfer in Click must have a unique target. This
means that every push *output*, and every pull *input*, must be attached to
exactly one connection. (Push inputs and pull outputs, in contrast, may be
connected more than once.) Therefore, every push output and pull input is
associated with exactly one (element, port#) pair. (For push outputs, these
correspond to the downstream input; for pull inputs, they correspond to the
upstream output. Confused yet?) We store those pairs in the Port data
structures. However, push *inputs* and pull *outputs* may be connected more
than once; the corresponding Port objects contain null pointers.

So the Router's initialization pattern looks like this:

1. Configure elements, so we know how many input + output ports they have.
(Router::initialize)
2. Figure out which ports are push and which are pull. May require some
constraint solving, using the list of connections, because of agnostic
ports. (Router::check_push_and_pull)
3. Complain if:
   * A connection goes push -> pull. (Router::check_push_and_pull)
   * A push output or pull input is connected 0 times, or more than once.
(Router::check_hookup_completeness)
   * A push input or pull output is connected 0 times.
(Router::check_hookup_completeness)
   * A connection involves a nonexistent port. (Router::check_hookup_range)
4. Store information about push connections in the Element::Port
structures for the outputs, and information about pull connections in the
structures for the inputs. (Router::set_connections)

This may be more information than you need, I'm not sure.

> and knowing which methods are called when an element is activated
> (especially when going through a push or pull connection).

Basically it's just a chain of Element::push() calls (or Element::pull()
calls). The Element::Port::{push,pull} functions are essentially syntactic
sugar.

The endpoints of a push or pull path are activated usually because they are
on a task list or timer list. The relevant header files are task.hh and
timer.hh; relevant functions are Element::run_task() and
Element::run_timer() (although elements can choose different functions, and
older versions of Click used Element::run_scheduled()).

> If you could provide any information that would make this clearer for me
> (an explanation, or a pointer to files or sections of files that I should
> look at), I would very much appreciate it.

Hope this has helped.

Eddie