linkage between otcl and c++ in n otc ot ns2teerawat/publications/ns2/w03-otcl.pdf · c++ variable...

Linkage Between OTcl and C++ in Linkage Between OTcl and C++ in NSNS22

Linkage Between OTcl and C++ in Linkage Between OTcl and C++ in NSNS22NSNS22NSNS22

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

PPreed

pared

repa

k: T. Issariyaku

yby

at

erwatn OTcOTOTOTOTOTOT

NSNS22

Tee

NSNS

ulya

kul

sariy

a

Issa

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

– Class Tcl– Class TclCommand– Class TclCommand

• Component binding:Cl T lCl– Class TclClass,

– Class TclObject, and Cl V– Class InstVar


PPreed

ObV

paredInstV

repa

k: T. Issariyaku

yby ass,

bject

at

erwat

Teeding:

ulya

kul

sariy

a

Issa

e

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

C ilQ: What is the NS2 component which link C++ and OTcl ?– Compiler

– Fast to run; Slow to changeOTcl

which link C++ and OTcl ?

• OTcl– Interpreter

Slow to run; Fast to change– Slow to run; Fast to change• Hierarchy

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

• Why two languages?� C++ coding stylesTextbook: T. Issariyakul and E. Hossain, Introduction to Network Simulator NS2, Springer 2008.

• Why two languages? � C++ coding styles3

P

d

ympi

pared

Compicl = In

y tw

Prepk: T. Issariyaku

hy twyaby

Fasat

Wwhich

erwat

hangewhich

Tee

ulak

ulitio

sariyositi

Issa

hat

Three C++ Coding Stylesg y1. Basic C++

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

link speed)

2. C++ coding with input arguments– Use parameters input argument (argv argc)Use parameters input argument (argv,argc)– E.g., “prog <num_node> <link_speed>”– Invocation “prog 10 3”

h f h– What if there are too many parameters?

3 C++ coding with input files � NS23. C++ coding with input files– Put input parameters in a configuration file– No need to change C++ code

NS

– One input argument—the filename.– E.G., “prog config.txt” 4

PPrepdwith

pared

g witnput pa

o need paOne i– E.G.,

yby are

at

erwatgumen

gume

Tee

argumode> <link0 3”

ulya

kul

sariy

a

Issa

s (e.g.,

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

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


PPreed

pared

repa

k: T. Issariyaku

n

by

ation at

erwatnder ~

ns

Tee

nsment=

ulya

kul

es

sariy

ayles

Issa

Why Tcl/OTcl?y• Problem 1:

– Reading Tcl files from C++ is hard!– Use Tcl

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

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

f h lTextbook: T. Issariyakul and E. Hossain, Introduction to Network Simulator NS2, Springer 2008.

– Define them in OTcl6

PPrepa

k: T. Issariyaku

Depareed

:

ede comp+ makffi

yby

at

erwat

Teesses �

ulya

kul

sariy

a

Issa

hard!

C++/OTcl ArchitectureC++/OTcl Architecture• C++: Internal mechanismnternal mechan sm• OTcl: User interface

MonitorFiles:

Tcl script (input);– Monitor– Keyboard

T l Si l ti S i t/O t t fil

p pOutput file

– Tcl Simulation Script/Output file

UserInterface

Screen(output)

Keyboard(input)

7

P

ed

edededpa

redpa

redpa

redaaarearearerareparaare

d

Prepa

ybyby

bybyby

at

erwat

i t

TeeScrip

ulya

kul

e

sariy

aure

Issa

C /OT l C mp n nts: C Cl ss sC++/OTcl Components: C++ Classes

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

– Class Tcl: Access to Tcl/OTcl interpreter– Class InstVar: Define C++ class variables which is

b d l l blbound to OTcl class variables– Class TclObject: C++ object + OTcl interface

Cl T lCl Bi d C d OT l Cl– Class TclClass: Bind C++ and OTcl Classes– Class TclCommand: Global command

Class EmbeddedTcl: Translate OTcl to C++– Class EmbeddedTcl: Translate OTcl to C++


PPre

d

Cbed

pared

Embed

repa

k: T. Issariyaku

yby s:

b

Bomman

at

erwatcl/OTc

e C++

Teeass vart: C++

ulya

kul

s s

sariy

aasses

Issa

from C

C++/OTcl Component FunctionalityC++/OTcl Component Functionality

T l I k T l f C- Tcl: Invoke Tcl from C++- TclCommand: Invoke C++ from OTcl- EmbeddedTcl: Translate OTcl to C++

C++ OTcl

TclObject: C++ & Tcl interfaces

C++ Class OTcl Class

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

C i bl OT l i blInstVar: Bind variables

C++ variable OTcl variable

9

P

ed

edepa

redaredre

Prepa

yby

Inby

at

OT

erwat

+ & Tc

wa

TeeC++ & T: Bind c

Te

ulya

kul

ity

sariy

anality

Issa

om OTcto

C++/OTcl Components andC++/OTcl Components and NS2 Directories~ns ~tclcl


PPre

ded d

paredare

dare

repa

k: T. Issariyaku

yby

bb

at ttataterw

atwatwarw

arw

arw

TeeTeTeTeTeeeTee

ulya

kul

sariy

ad

sariy

Issa

Iss






PPreed

ObV

paredInstV

repa

k: T. Issariyaku

yby ass,

bject

at

erwat

Teeding:

ulya

kul

sariy

a

Issa

e

Cl ss T lClass Tcl

• Access OTcl from C++• 5 Main Functionalities5 Main Functionalities

– Obtain the Tcl instance– Invoke OTcl statement from C++Invoke OTcl statement from C++– Pass/Receive results to/from the OTcl– Report error– Report error– Retrieve the reference to TclObjects


PPreed

t

pared

repa

k: T. Issariyaku

yby

he ref

at

erwate

ent f

Tee

mentesults

ulya

kul

sariy

a

Issa

Class Tcl: Main Functionalitiesa Ma n Fun na• Obtain the Tcl instance What is the

difference• Invoke OTcl procedures

– Tcl::eval(char* str)

difference between?

– Tcl::evalc(const char* str)

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


ed d

ared

valf(c

aPPrPre

yby onst chby

at tatwa

TT

ulya

kul

s

sariy

asa

W

Issa

Issa

Is

Class Tcl: Main Functionalitiesa Ma n Fun na• Pass results to the OTcl

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

Suppose $d =10.What would

– Tcl::result(const char* fmt) appearon the screen as a result of ?

• Receive results from the OTcl

a result of ?

f– Tcl::result()


P

ed sult

paredesult()

par

Prepa

k: T. Issariy

pabyby

t terwrw

Teehar* fmt

T

ulya

kul

s

sariy

a

Issa

I






PPreed

ObV

paredInstV

repa

k: T. Issariyaku

yby ass,

bject

at

erwat

Teeding:

ulya

kul

sariy

a

Issa

e

Class TclCommandClass TclCommand• Invoke C++ from the OTcl (reverseInvoke C++ from the OTcl (reverse

of Class Tcl)Available globally• Available globally.

• Not recommended (non OOP). • Use command in TclObject

(discussed later)(discussed later)• Examples

ns version– ns-version– ns-random

fil / / / iTextbook: T. Issariyakul and E. Hossain, Introduction to Network Simulator NS2, Springer 2008.

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

Prek: T. Issariyaku

ed s

ion

pared

rsionrandofi

repaee fi

by tat

at

erwat

ed (no

Teein Tcer)

ulya

kul

ariya

(rev

Iss

cl (r






PPreed

ObV

paredInstV

repa

k: T. Issariyaku

yby ass,

bject

at

erwat

Teeding:

ulya

kul

sariy

a

Issa

e

C mp n nt BindinComponent Binding• Applicable only to bounded hierarchyApplicable only to bounded hierarchy

• Three major componentsClass name� TclClass– Class name � TclClass

– Object (or instance) � TclObjectClass variable� InstVar– Class variable � InstVar

18

P

ed

joame�

pared

ame ject (o

ass v

Prepalass

yyyby

r com

tat tteerw

aterw

arw

arwererwrwwww

aerw

at

TeeTTeeee

TeeTeTe

TT

ulya

kul

ariya

erarc

Iss

iera

IsIs

C mp n nt BindinComponent Binding• Every C++ bounded class has a corresponding OTcl Every C bounded class has a correspond ng O cl

class• What happen when the following OTcl statement

is executed?is executed?

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

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


Preed

Bind

paredect: Bin

Var: Bi

repa

k: T. Issariyaku

byy

pompotclcl

cl

at

ing

erwat

Teecreated

ulya

kul

ariya

espon

Iss

resp

OT






PPreed

ObV

paredInstV

repa

k: T. Issariyaku

yby ss,

bject

at

erwat

Teeding:

ulya

kul

sariy

a

Issa

e

I. Class TclClass• Bind Classname (e.g., Agent/TCP �

TcpAgent)TcpAgent)?

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

Textbook: T. Issariyakul and E. Hossain, Introduction to Network Simulator NS2, Springer 2008.• TcpClass derived from (TclClass)

21

P

dlas

pare

g clasic =(

Prepa

k: T. IssariyTcpCla

Iss i k

b

ulya

kul

sariy

a�

Issa

Class TclClass• Bind Classname (e.g., Agent/TCP �

TcpAgent)TcpAgent)

• TclClass takes an OTcl class name as an• TclClass takes an OTcl class name as an input argument.F ( ) h d T A

Textbook: T. Issariyakul and E. Hossain, Introduction to Network Simulator NS2, Springer 2008.• Fn create(.) returns the created TcpAgent

pointer 22

PPrek: dake

pared

takargum

repa

I i kcrea

poi T. Issariy

b

ulya

kul

sariy

a�

Issa

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

of TclClassof TclClass2. Declare a static mapping variable right at

the declarationthe declaration3. Feed the OTcl classname as an input

argument to class TclClassargument to class TclClass4. Define function create(.), returning the

created C++ objectQ: What is the purpose of having class TcpClass ?

What is not possible to do without TcpClass?

created C++ object.

p p

new Agent/TCP � create a TcpAgent objectQ: Why do we declare TcpClass as static ?

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

Q: Why do we declare TcpClass as static ?

We need unique class mapping objects 23

P

ed t i

t is n

paredAgen

papaQ

PrePrepa

PreW

o

bybybythe pu

obat

g

erwatsname

Tcl

Tee

s Tcon cre

ulya

kul

ss

sariy

aerived

Issa

varia






PPreed

ObV

paredInstV

repa

k: T. Issariyaku

yby ass,

bject

at

erwat

Teeding:

ulya

kul

sariy

a

Issa

e

II Class TclObjectII. Class TclObject• TclClass:

C t “h k” b t OT l d C l– 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 TclClassj– How to construct such the C++ object ? � TclObject !!

• TclObject– C++ object & OTcl functionalities– In the bound hierarchies

C++: Based class TclObject; see /tclcl/tclcl h• C++: Based class = TclObject; see ~/tclcl/tclcl.h• OTcl: Based class = SplitObject see ~/tclcl/tcl-object.tcl

– A user creates a TclObject from the OTcl– NS2 automatically creates a “shadow” C++ object

h d Th bj idi i diff lTextbook: T. Issariyakul and E. Hossain, Introduction to Network Simulator NS2, Springer 2008.

– Shadow � The same object residing in different class hierarchy 25

P

ed

paredr create

autoh d

Prepa

k: T. Is

Shadohierassariyaku

ysby ass

ed class

at

NSined

erwat++ obj

Teeunctionaarchies

ulya

kul

sariy

al

Issa+ clas

2 cre

Class TclObject: Outline• Object construction: What happen when

“new” is executed.• OTcl commands: Invoking C++ from the

OTcl. • C++ and OTcl class variable binding• Others• Others

– Reference to TclObjectsObject destruction (similar to the– Object destruction (similar to the construction)


PPrepare

d

ce destt dest

struct

repa

k: T. Issariyaku

yby

to Tc

at

erwatking C

Teeass var

ulya

kul

sariy

atline

Issa

t happ

TclObject Construction• NS2 creates object using a global OTcl

procedureprocedure new <className> [<args>]

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

alloc + init


PPrepk: T. Issar

y

at

[

rwat

TeTe

ulya

kul

n

sariy

abal OT

Issa

args

TclObject Construction• Procedure “create” invokes

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

• Example:• Example:Invoke the same instproc ofinstproc of the parent class

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


Pp

Prepa

k: T. Issariyaku

at wateree

ulya

kul

n

sariy

a

Issa

ction

TclObject Construction• Example: TCP

( SplitObject ) ( TclObject )

OTcl C++

( p j ) ( j )

…

Agent/TCP TCPAgentAgent/TCP TCPAgent


PPrepare

ded dTCP

rededed

t/TCP

rerep

ak: T. Issariyaku

yby

bb

atatat( Tc

erwatwatwat(

erTeeT

e

ulya

kul

n

sariy

asaIss

aIsIs

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

Agent/TCP::initConstructor of TcpAgent

$self init<other stuff>

TcpClass::create shadow

S litObj t i it

TcpClass::create_shadow

new TcpAgent();

SplitObject::init

TcpClass::create-shadow TclClass::create_shadow

Textbook: T. Issariyakul and E. Hossain, Introduction to Network Simulator NS2, Springer 2008.class_tcp.create(…); 30

P

dd dt i

pared

ject::i

ass::cre


paep

yby

bb

atat aterw

atwatwatC

Tee

ulya

kul

n

sariy

a)?

Issa)

and 2. II

OTcl Commands• Example: $ns connect $tcp $sink• The syntax is• The syntax is

<object> <command_name> [<args>]• <command_name> can be

1 An instproc of <object>1. An instproc of <object>2. OTcl command associated with the

bj t<object>Q: From the above example

bj t ( $ )-<object> = ( $ns )-<command_name> = ( connect )-<args> = ( $tcp $sink )


-<args> = ( $tcp $sink )31

P

ed e ab

( $

pared= ( $

mand_ns> = (


gs> = yby

bov

at

d_na

erwatan be

<obj

Teeof <obmand a

ulya

kul

sariy

a$sink

Issa

am

OTcl CommandsOTcl Commands• The detail of Tcl command is defined in C++

f ifunction command(argc,argv)

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

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

• Return either Tcl codes (e.g., TCL_OK, TCL_ERROR)_ )

• Invoke the same function of the parent class.


PPrepare

d OR)

ed

)e the

.

repa

k: T. Issariyaku

<a

by

er Tcat

c,arg

erwats

vecto

Tee,comman

>

ulya

kul

sariy

aefine

Issa

gv)

OTcl Commands• Q: Which hierarchy do we define ( C++ ) and

invoke (OTcl ) an OTcl command ? • Example:

<command_name>

Returning

Invoking the same functionf th t l

Q: Why?

gTCL_OK

of the parent class What’s the benefit?Is it still return a Tcl code?

33


33

P

I

ar

o

Prek: T. Issariyakuep

voby

t

ee

ulya

kul

sariy

a) an

Issa

OTcl CommandsOTcl CommandsTo define an OTcl command:To define an OTcl command:

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

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

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


PPreed

nd.

pared

und.

repa

k: T. Issariyaku

io

by tio

ass if at

nd

erwato mat

with a

Teeode“

ulya

kul

ariya

mman

Iss

ommd(arg

OTcl CommandsOTcl CommandsQ: How do we invoke the commandQ How do we invoke the command

“eventtrace” from the OTcl?

$tcp eventtrace <EVENT>


PPrepare

d$tcp

repa

k: T. Issariyaku

at at

ulya

kul

ariya

mman

Iss

ommOTcl?

Component Binding

• Tclclass � Bind classnames• TclObject � Bind objects

(shadowing)(shadowing)• OTcl command � Bind functions• Variable binding � Bind variables


PPreed

pared

repa

k: T. Issariyaku

ybybindinat

nd

erwat� Bin

Teed �

ulya

kul

sariy

ang

Issa

d c

Variable Binding• 2 Tasks1 Binding variables:1. Binding variables:

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

• Class InstVar2. Setting the default values: The value

assigned to instvars upon objectassigned to instvars upon object construction


PPrepare

ddd tned tstruc

repa

k: T. Issariyaku

ybyhe dat

erwat

ariaber v

Teeher Var

ulya

kul

sariy

ag

Issa

Binding VariablesBinding Variables• Syntax y

bind(“<ovar>”,&<cvar>);– <ovar> = OTcl class variable name– <ovar> = OTcl class variable name– <cvar> = C++ class variable name

d d t b th– <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>);


Boolean: bind_bool( <ovar> ,&<cvar>);38

P

ed dth

arede:

oolea

Prepa

k: T. Issariyaku

Booleybybi

at

criabl

erwaariab

varia

Teea > nee

ulya

kul

sariy

a

Issa

cvar>

Binding VariablesBinding Variables• E.G.,

OTcl C++Class Agent/TCP TcpAgentg p gObject name otcp ctcpClass variable t seqno t seq noClass variable t_seqno_ t_seq_no_


PPrepa

repa

k: T. Issariyaku

atCP

erwatwa

rweqno

TeeTeeseqn

ulya

kul

sariy

asaIss

asIsC+

Setting the Default ValuesSetting 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><Class_Name> set <instvar> <value>• E.G.,

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

ak: T. Issariyaku

y

at

ng

rwat

et <in

Tee

et <

ulak

ulues

sariy

aluelt.tc

Iss

lt.tme

Reference to TclObjects

C++ OTclBase class TclObject SplitObjectVariable name String (e.g., tcp) String (e.g., tcp)g ( g , p) g ( g , p)Reference value Hexadecimal:

0x<value>Decimal string:

o<value>a u _o a uExample 0xd6f9c0 _o10


PPreed

dpa

red

repa

k: T. Issariyaku

by

by

x

bybbbyb0xdat

erwatat

rw

t(e.g.

Teeee

g ( gexadecim

al

ulya

kul

sariy

aject

Issa

IsIsO






PPreed

ObV

paredInstV

repa

k: T. Issariyaku

yby ass,

bject

at

erwat

Teeding:

ulya

kul

sariy

a

Issa

e

III. Class InstVar• Recall: Variable binding

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

• What are the difference? � Make it easier for l h lmanipulation in the OTcl

• Derived class– Real Class InstVarReal– Integer Class InstVarInt– Boolean Class InstVarBool– Bandwidth Class InstVarBandwidth

Ti Cl I V Ti– Time Class InstVarTime


PPreed

pared

repa

k: T. Issariyaku

yCby Cla

Cla

at

tytype

erwatyp

typ

� Mak

Tees I

ulya

kul

sariy

ar

Issa

e = (

Class InstVar• Real and Integer

e<x>�x 10<x>– e<x> �x 10<x>

– E.G.,


PPrepare

d

repa

k: T. Issariyaku

at

erwat

ee

ulya

kul

sariy

a

Issa

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

“k” “K” 103– “k” or “K” = 103

– “m” or “M” = 106

b bi B B– b = bits; B = Bytes• E.G.,


PPrepare

repa

k: T. Issariyaku

at

erwat

Teees

ulya

kul

sariy

a

Issa

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

– “m” = 10-3

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

– “p” = 10-12

E G• E.G.,


Prepare

repa

k: T. Issariyaku

yby

at

erwat

Tee

ulya

kul

sariy

a

Issa

Class InstVarClass 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)


PPrepa

repa

k: T. Issariyaku

atse(0

erwaalse(0

Tee

ulya

kul

sariy

a

Issa

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

resultsF C k [ T l l( ) ]– From C++: Invoke [ Tcl::eval(…) ],

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

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

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


PPreparee

d ( T

ed

(vari

repa

k: T. Issariyaku

w

by ow

e: ( Tcat [ T

erwat [ T

eceiveomm

TeeCommTclObjng

ulya

kul

sariy

a

Issa

r rece

Related files/ s/ mm /mis• ~/ns/common/misc.cc

• ~/tclcl/tcl-object.tcl• ~/ns/tcl/lib/ns-default.tcl


PPreed

pared

repa

k: T. Issariyaku

yby

at

erwat.tcl

Tee

ulya

kul

sariy

a

Issa

linkage between otcl and c++ in n otc ot ns2teerawat/publications/ns2/w03-otcl.pdf · c++ variable...

Documents