linkage between otcl and c++ in l nkage between o cl and c n

Linkage Between OTcl and C++ in Linkage Between OTcl and C++ in Linkage Between OTcl and C++ in Linkage Between OTcl and C++ in L nkage Between O cl and C n L nkage Between O cl and C n NS2NS2

L nkage Between O cl and C n L nkage Between O cl and C n NS2NS2

Textbook: T. Issariyakul and E. Hossain, Introduction to Network Simulator NS2, Springer 2008. 1

Outline• NS2 C++/OTcl Architecture• NS2 C++/OTcl Architecture• Environment binding:

– Class Tcl– Class TclCommand– Class EmbeddedTcl

Component binding:• Component binding:– Class TclClass, – Class TclObject, and – Class InstVar

• Summary


NS2: C++ and OTcl CompositionNS2: C++ and OTcl Composition• Two language architecture: C++ and OTcl• C++

– Compiler– Fast to run (run on machine codes) ( )– Slow to change (need compliation)

• OTcl– InterpreterInterpreter– Slow to run; Fast to change

• HierarchyC C il d Hi h

Q: What is the NS2 component which link C++ and OTcl ?

T lCL– C++ = Compiled Hierarchy– OTcl = Interpreted Hierarchy

• Why two languages? C++ coding styles

TclCL


Th C C di S lThree C++ Coding Styles1. Basic C++ 1. Basic C

prog.ccprog.h

prog.exe

Compile

output

Execute“>>prog 10 3”

– Compile and create “prog.exe”– Recompile for every minor changes (e.g.,

b f d li k d)

output


number of nodes, link speed)

Th C C di S lThree C++ Coding Styles2. C++ coding with input arguments

Keyboard(input)

prog.ccprog.h

prog.exe

10 nodes,3 Mbps

Compile

output

Execute“>>prog 10 3”

– Use parameters input argument (argv,argc)– E.g., “prog <num_node> <link_speed>”– Invocation: “prog 10 3”

output


Invocation: prog 10 3

– What if there are too many parameters?

Th C C di S lThree C++ Coding Styles3. C++ coding with input files

Keyboard(input)config.txt

prog.ccprog.h

prog.exe

10 nodes,3 Mbps

Put input parameters in a configuration file

Compile

output

Execute“>>prog config.txt”

– Put input parameters in a configuration file– No need to change C++ code– One input argument—the filename– E.G., “prog config.txt”

output


– This is NS2 style!!– The configuration file is called “Tcl Simulation script”

NS2 and C++ Coding StylesNS2 and C++ Coding Styles

• C++ coding with input files• C++ coding with input files• E.G., “>>ns myfirst_ns.tcl”• C++ codes: Located under /ns/*• C++ codes: Located under ~/ns/*• C++ executable file: ns• The input argument=?: (myfirst ns tcl )The input argument=?: (myfirst_ns.tcl )• A configuration file=?: (myfirst_ns.tcl )


Wh T l/OT l?Why Tcl/OTcl?• Problem 1: Problem 1

– Reading a configuration file from C++ is hard!– Use Tcl

• Problem 2: – C++ contains classes Tcl is not OOP– Use OTcl

• Problem 3: • Problem 3: – Some components are easy to implement– C++ make things complicated

Textbook: T. Issariyakul and E. Hossain, Introduction to Network Simulator NS2, Springer 2008.

– Define them in OTcl8

C++/OTcl Architecture/ u• C++: Internal mechanism

OT l U i f• OTcl: User interface– Monitor

K b d

Files:Tcl script (input);

Output file– Keyboard– Tcl Simulation Script/Output file

UserI t fInterface

Screen(output)

Keyboard(input)

9

NS2 ProcessN• Start from Tcl simulation script• For each line:For each line:

• Execution path:Tcl OTcl C++• Returning path: C++ OTcl Tcl (next line)

• Example:Tcl Simulation Script:

# fi t t l

OTcl (interpreted) hierarchy:

Si l Li k i t i it {#myfirst_ns.tcl…$ns duplex-link $n0 $n2

100Mb 5ms DropTail

SimpleLink instproc init {… $queue target $link … }

C++ (compiled) hierarchy:

int Connector::command(int argc, const char*const* argv){

…if (strcmp(argv[1], "target") == 0) {if (target != 0)if (target_ != 0)

tcl.result(target_->name());return (TCL_OK);}

}10

C++/OTcl Components: C++ ClassesC++/OTcl Components: C++ Classes

• Provide an access to OTcl from C++Provide an access to OTcl from C++• 6 main classes:

– Class Tcl: Access to Tcl/OTcl interpreterass c cc ss to c /O c nt rpr t r– Class InstVar: Define C++ class variables which is

bound to OTcl class variablesClass TclObject: C++ object + OTcl interface– Class TclObject: C++ object + OTcl interface

– Class TclClass: Bind C++ and OTcl Classes– Class TclCommand: Global command– Class EmbeddedTcl: Translate OTcl to C++


C++/OTcl Component FunctionalityC /OTcl Component Functionality

- Tcl: Invoke Tcl from C++l l

C++ OTcl

- TclCommand: Invoke C++ from OTcl- EmbeddedTcl: Translate OTcl to C++

-TclObject: C++ & Tcl interfaces-TclClass: Bind classnames

C++ Class OTcl Class

InstVar: Bind variablesC++ variable OTcl variable

InstVar: Bind variables

12

Q: Why Translating Otcl to C++?Faster at runtime

C++/OTcl Components and pNS2 Directories

~tclcl~ns





• Summary


Class Tcl• Access OTcl from C++Access OTcl from C++• 5 Main Functionalities

1 Obtain the Tcl instance1. Obtain the Tcl instance2. Invoke OTcl statement from C++3. Pass/Receive results to/from the OTcl4. Report error5. Retrieve the reference to TclObjects


Class Tcl: Main Functionalities1. Obtain the Tcl instance

Wh t i th

2 I k OT l d

What is the difference between?

2. Invoke OTcl procedures– Tcl::eval(char* str)

– Tcl::evalc(const char* str)


Class Tcl: Main Functionalities2. Invoke OTcl procedures (cont.)p ( )

– Tcl::evalf(const char* format,…)

3. Receive results from the OTcl– Tcl::result()


Class Tcl: Main Functionalities3. Pass results to the OTcl

– Tcl::result(const char* str):

– Tcl::result(const char* fmt)





• Summary


Class TclCommand• Reverse of Class Tcl

(Invoke OTcl commands from C++) • Invoke C++ codes from the OTcl domain

A il bl l b ll • Available globally. • Not recommended (non OOP). • Use command in TclObject (discussed later)Use command in TclObject (discussed later)• Examples

– ns-versionns rand m– ns-random

• See file ~/ns/common/misc.cc


Class Embedded Tcl• Translate OTcl C++ codeTranslate OTcl C code

• Why? Faster at runtimey

• Alternative method Define your OTcl ycodes (e.g., class definition) in the Tcl simulation script

• How: use Makefile


OutlineNS2 C++/OTcl Architecture• NS2 C++/OTcl Architecture

• Environment binding: Cl ss T l– Class Tcl

– Class TclCommand– Class EmbeddedTclClass EmbeddedTcl

• Component binding:– Class TclClass Class TclClass, – Class TclObject, and – Class InstVar


• Summary22

C Bi diComponent Binding• Applicable only to bounded hierarchy

C++ class OTclclass

Applicable only to bounded hierarchy

class class class

class class

class

class classclass

class classThe interpreted The compiled

one-to-one correspondence

phierarchy

phierarchy

• Three major componentsThree major components– Class name TclClass– Object (or instance) TclObject


j– Class variable InstVar

C Bi diComponent Binding• Every C++ bounded class has a corresponding OTcl

ly p g

class• What happen when the following OTcl statement

is executed?

• C++ counterpart is created!! (shadowing process) C counterpart is created!! (shadowing process) How? TclCL

• Main binding components: – Located in ~tclclLocated in tclcl– TclClass: Bind classname– TclObject: Bind the instance (or object)– InstVar: Bind class variables


Class TclClass• Bind Classname (e.g., Agent/TCP TcpAgent)n assnam ( .g., g / p g )?

• Mapping class name = TcpClass• Mapping class name = TcpClass• Static =( static mapping variable )=( class_tcp )• TcpClass derived from (TclClass)


TcpClass derived from (TclClass)

25

Class TclClass• Bind Classname (e.g., Agent/TCP TcpAgent)n assnam ( .g., g / p g )

T lCl takes an OTcl class name as an input • TclClass takes an OTcl class name as an input argument.

• Fn create(...) returns the created TcpAgent pointer


p g p

26

To Bind C++ and OTcl class1. Define a mapping class as a derived class of pp g

class TclClass2. Declare a static mapping variable right at the

declarationdeclaration3. Feed the OTcl classname as an input argument

to class TclClass4 D fi f ti t i th

Q: What is the purpose of having class TcpClass ?

4. Define function create(…), returning the created C++ object.

What is not possible to do without TcpClass?

new Agent/TCP create a TcpAgent object


Q: Why do we declare class_tcp as static ?

We need unique class mapping objects




• Summary


Cl T lCl A R iClass TclClass: A Review• Create a “hook” between OTcl and C++ class Create a hook between OTcl and C++ class

name

• When creating an OTcl object, NS2 creates a C++ object with the class name defined in j fTclClass

• How to construct such the C++ object ? TclObject !!


j29

Cl T lObjClass TclObject• C++ object & OTcl functionalitiesC object & OTcl functionalities• In the bound hierarchies

– C++: Based class = TclObject; see ~/tclcl/tclcl.hl d l – OTcl: Based class = SplitObject see ~/tclcl/tcl-

object.tcl

• A user creates a TclObject from the OTclj• NS2 automatically creates a “shadow” C++ object• Shadow The same object residing in different class

h hhierarchy


Cl T lObj O liClass TclObject: Outline• Object construction: What happen when Object construction: What happen when

“new” is executed.• OTcl commands: Invoking C++ from the OTcl. OTcl commands Invoking C from the OTcl. • C++ and OTcl class variable binding• OthersOthers

– Reference to TclObjects– Object destruction (similar to the construction)j ( )


T lObj C iTclObject Construction• NS2 creates object using a global OTcl procedure NS2 creates object using a global OTcl procedure

new <className> [<args>]

• E.g., “new Agent/TCP” TclClass

alloc + init


T lObj C iTclObject Construction• Procedure “create” invokesr c ur n

– alloc{…}: Allocate memory – init{…}: OTcl object construction

E l• Example:Invoke the same instproc of the parent classthe parent class

Belong to TclClass:Invoke C++ function Invoke C++ function “create(…)”


T lObj C iTclObject Construction• Example: TCPExample: TCP

OTcl C++

( SplitObject ) ( TclObject )…

Agent/TCP TCPAgent


T lObj C iTclObject Construction• Example: Create a TCP objectExample Create a TCP objectQ: OTcl command = ( new Agent/TCP )?Q: What does it do ? 1. ( alloc ), and 2. ( init )

Agent/TCP::init

$self initConstructor of TcpAgent

$self init<other stuff>

TcpClass::create shadow

SplitObject::initTcpClass::create-shadow

TcpClass::create_shadownew TcpAgent();


TcpClass::create shadow

TclClass::create_shadowclass_tcp.create(…);

35

OT l C dOTcl Commands• Invoke C++ statements from Tcl/OTcl environmentInvoke C statements from Tcl/OTcl environment• Example: $ns connect $tcp $sink• The syntax is<object> <command_name> [<args>]

•<command_name> can be1 A i t f 1. An instproc of <object>2. OTcl command associated with the <object>

Q: From the above example-<object> = ( $ns )-<command_name> = ( connect )


-<args> = ( $tcp $sink )

OT l C dOTcl Commands• The detail of Tcl command is defined in C++ The detail of Tcl command is defined in C

function of class TclObjectcommand(argc,argv)

– argc = no. of arguments– argv = an argument vector

• argv [0] = cmd• argv [0] = cmd, • argv[1] = <command_name>, • argv[n] = <args>, n > 1

R t ith T l d ( TCL OK • Return either Tcl codes (e.g., TCL_OK, TCL_ERROR)

• Invoke the same function of the parent classTextbook: T. Issariyakul and E. Hossain, Introduction to Network Simulator NS2, Springer 2008.

Invoke the same function of the parent class.37

OTcl CommandsQ Whi h hi h d d fi ( C ) d • Q: Which hierarchy do we define ( C++ ) and invoke (OTcl ) an OTcl command ?

• Example: Overriding TclObject::command(…)Example

<command_name>

In kin th s m f n ti n Q Wh

Returning TCL_OK

Invoking the same functionof the parent class

Q: Why? What’s the benefit?Is it still return a Tcl code?


a Tcl code?38

OT l C dOTcl CommandsTo define an OTcl command:To define an OTcl command:

1. Define function “command(argc,argv)”2 Use “if” statement to match 2. Use if statement to match

<command_name> with argv[1]3 Return a Tcl code3. Return a Tcl code4. Invoke function “command(…)” of the

parent class if the <command name> is parent class if the <command_name> is not found.


OT l C dOTcl CommandsQ: How do we invoke the command Q: How do we invoke the command

“eventtrace” from the OTcl?

$tcp eventtrace <EVENT>Textbook: T. Issariyakul and E. Hossain, Introduction to Network Simulator NS2, Springer 2008.

$tcp eventtrace <EVENT>40

R f T lObjReference to TclObjectsC++ OTclC OTcl

Base class TclObject SplitObject

Variable name String (e.g., tcp) String (e.g., tcp)g g g gReference value Hexadecimal:

0x<value>Decimal string:_o<value>

Example 0xd6f9c0 _o10





• Summary


C Bi diComponent Binding• Tclclass Bind classnamesTclclass Bind classnames

• TclObject Bind objects• TclObject Bind objects

• OTcl command Bind functions• OTcl command Bind functions

• Variable binding Bind variables• Variable binding Bind variables


V i bl Bi diVariable Binding• 2 Tasks2 Tasks1. Binding variables:

• A change in one variable Auto change in A change in one variable Auto. change in another variable

• Class InstVar

2. Setting the default values: The value i d i bj assigned to instvars upon object

construction


Bi di V i blBinding Variables• Syntax

bind(“<ovar>”,&<cvar>);– <ovar> = OTcl class variable name– <cvar> = C++ class variable name– <ovar> and <cvar> need not be the same

• Other types– Regular: bind(“<ovar>”,&<cvar>);

– Bandwidth: bind_bw(“<ovar>”,&<cvar>);

– Time: bind_time(“<ovar>”,&<cvar>);


– Boolean: bind_bool(“<ovar>”,&<cvar>);45

Bi di V i bl E lBinding Variables: ExampleOTcl C++OTcl C++

Class Agent/TCP TcpAgent

Object name otcp ctcpObject name otcp ctcp

Class variable t_seqno_ t_seq_no_


S i h D f l V lSetting the Default Values• File ~/ns/tcl/lib/ns-default tclFile ~/ns/tcl/lib/ns-default.tcl• Not doing so warning message

• Syntax: <Class_Name> set <instvar> <value>

• E.G.,


Class InstVar• Recall: Variable bindingRecall: Variable binding

– bind (“<ovar>”,&<cvar>); type = ( regular,integer,real )– bind_bw (“<ovar>”,&<cvar>); type = ( bandwidth )– bind_time (“<ovar>”,&<cvar>); type = ( time )

t ( b l )– bind_bool (“<ovar>”,&<cvar>); type = ( boolean )

• What are the difference? Make it easier for manipulation in the OTclm p

• 5 derived classes– Real Class InstVarReal– Integer Class InstVarInt

B l Cl – Boolean Class InstVarBool– Bandwidth Class InstVarBandwidth– Time Class InstVarTime


Class InstVarR l d I t• Real and Integer– e<x>x 10<x>

– E.G.,


Class InstVar• Bandwidth = Integer + UnitBandwidth = Integer + Unit• Unit:

– “k” or “K” = 103k or K 10– “m” or “M” = 106

– b = bits; B = Bytesy• E.G.,


Class InstVar• Time = Real + UnitTime = Real + Unit• Unit:

– “m” = 10-3m 10– “n” = 10-9

– “p” = 10-12

• E.G.,


Class InstVar• Boolean = {True or False}Boolean = {True or False}• See the first letter only• True (nonzero or T)/ False(0 or F)• True (nonzero or T)/ False(0 or F)





• Summary


Summary• NS2 = C++ with input fileNS2 C with input file• Execute statements and/or receive/pass

results– From C++: Invoke [ Tcl::eval(…) ],

Pass/Receive [ Tcl::result(…) ]– From OTcl: [ TclCommand ] From OTcl: [ TclCommand ],

[ TclObject::command(…) ]• Binding/Shadowing

– Class name: ( TclClass )– Objects: ( TclObject )– Class variables: ( InstVar )


– Class variables: ( InstVar )54

linkage between otcl and c++ in l nkage between o cl and c n

Documents