[Click] port_count()

[Eddie Kohler]

Hello from Ely, Minnesota!

The Click sources are collecting doxygen documentation comments.  This process 
will probably complete never, but soon you will be able to see the results on 
the web site.  For now, "doxygen doc/Doxyfile".

Important source changes:

* String::cc() is deprecated, in favor of String:c_str() (which is how the C++ 
standard library spells it).

* Added a new method, Element::port_count(), to specify how many ports each 
element can have.  Documentation is pasted below.  This method is now 
preferred strongly to "Element(ninputs, noutputs)" constructors, 
set_ninputs(), set_noutputs(), add_input(), add_output(), notify_ninputs(), 
and notify_noutputs(), since it is simpler and lets us check the configuration 
sooner.  All those other methods are now deprecated.

* All elements in the repository have been updated accordingly.  Mistakes may 
have been made!  Sorry in advance.

Offline now,
Eddie


const char * Element::port_count() const [virtual]

Called to fetch the element's port count specifier.

An element class overrides this virtual function to return a C string 
describing its port counts. The string gives acceptable input and output 
ranges, separated by a slash. Examples:

"1/1"
     The element has exactly one input port and one output port.
"1-2/0"
     One or two input ports and zero output ports.
"1/-6"
     One input port and up to six output ports.
"2-/-"
     At least two input ports and any number of output ports.
"3"
     Exactly three input and output ports. (If no slash appears, the text is 
used for both input and output ranges.)
"1-/="
     At least one input port and the same number of output ports.

These ranges help Click determine whether a configuration uses too few or too 
many ports, and lead to errors such as "'e' has no input 3" and "'e' input 3 
unused".

Click extracts port count specifiers from the source for use by tools. For 
Click to find a port count specifier, the function definition must appear 
inline, on a single line, inside the element class's declaration, and must 
return a C string constant. It should also have public accessibility. Here's 
an acceptable port_count() definition:

  const char *port_count() const     { return "1/1"; }

The default port_count() method effectively returns "0/0". (In reality, it 
returns a special value that causes Click to call notify_ninputs() and 
notify_noutputs(), as in previous releases. This behavior is deprecated; code 
should be updated to use port_count() semantics.)

The following names are available for common port count specifiers.

     * PORTS_0_0 for "0/0"
     * PORTS_0_1 for "0/1"
     * PORTS_1_0 for "1/0"
     * PORTS_1_1 for "1/1"

Since port_count() should return a C string constant with no other processing, 
it shouldn't matter when it's called; nevertheless, it is called before 
configure().