Bug 764 - feature request: non-doxygen trace source introspection program needed
feature request: non-doxygen trace source introspection program needed
Status: RESOLVED MOVED
Product: ns-3
Classification: Unclassified
Component: documentation
ns-3-dev
All All
: P5 normal
Assigned To: ns-bugs
:
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2009-12-03 10:28 EST by Tom Henderson
Modified: 2020-02-03 14:47 EST (History)
6 users (show)

See Also:


Attachments
sample output file (2.09 KB, text/plain)
2011-09-14 00:18 EDT, Tom Henderson
Details

Note You need to log in before you can comment on or make changes to this bug.
Description Tom Henderson 2009-12-03 10:28:56 EST
Reminder that we should make a version of utils/print-introspected-doxygen.cc that doesn't dump output into doxygen but instead dumps a list of all paths to a text file.
Comment 1 Mitch Watrous 2011-09-13 17:17:56 EDT
Do we want the list of trace sources or the list of attribute paths or both?

If both, should these lists be written to different files or the same file?
Comment 2 Tom Henderson 2011-09-14 00:17:53 EDT
(In reply to comment #1)
> Do we want the list of trace sources or the list of attribute paths or both?
> 
> If both, should these lists be written to different files or the same file?

I would suggest prototyping the following.  

./waf --print-introspected-doxygen retains its current behavior.
./waf --print-introspected would dump all of the information into a single text file "ns3-objects.txt" (we can rename this later if needed).  This type of information would be formatted such as the attached text file (which I just copy/pasted from the TypeId doxygen documentation from two classes).

I do not care strongly that the eventual output is formatted exactly like I've attached, only that it has this kind of information.  Possible additional output files would be "ns3-attributes.txt" (the list of all attributes), "ns3-trace-sources.txt" (the list of all trace sources) and "ns3-global-values.txt" (all global values) but I would just suggest to start with one for now.
Comment 3 Tom Henderson 2011-09-14 00:18:50 EDT
Created attachment 1245 [details]
sample output file
Comment 4 Mitch Watrous 2011-09-14 18:38:09 EDT
Right now print-introspected-doxygen.cc is writing an html file.

Could the html file just be converted to a text file using a tool?

What is the purpose of having a text file?
Comment 5 Mitch Watrous 2011-09-14 19:54:18 EDT
Right now print-introspected-doxygen.cc is writing an html file.

Could the html file just be converted to a text file using a tool?

What is the purpose of having a text file?
Comment 6 Tom Henderson 2011-09-14 23:59:27 EDT
(In reply to comment #5)
> Right now print-introspected-doxygen.cc is writing an html file.
> 
> Could the html file just be converted to a text file using a tool?
> 
> What is the purpose of having a text file?

I personally would find it more convenient to have a file easily accessible (i.e. not found in a doxygen directory) that doesn't have html markup, so I don't have to open a web browser to quickly find this information.  I find myself opening up browsers and/or typing ./waf --doxygen when I need to find a trace or attribute path.

I'm not opposed to other solutions such as converting the html file if that is easier to create and maintain.
Comment 7 Mitch Watrous 2011-09-15 19:17:25 EDT
Do you want the classes in the file to be in alphabetical order?

Now they are not sorted and it would take more work to sort them.
Comment 8 Mitch Watrous 2011-09-20 15:33:47 EDT
I made the introspection program (print-introspected-doxygen.cc) generate a text file if requested.

Here is a very abbreviated version of the text file now being generated:


===============================================================

static TypeId ns3::AarfcdWifiManager::GetTypeId (void)


This method returns the TypeId associated to ns3::AarfcdWifiManager.

This object is accessible through the following paths with Config::Set and Config::Connect:

    * /NodeList/[i]/DeviceList/[i]/$%ns3::%AlohaNoackNetDevice/Phy/$%ns3::%AarfcdWifiManager

    * /NodeList/[i]/DeviceList/[i]/$%ns3::%AlohaNoackNetDevice/Phy/$%ns3::%WifiNetDevice/RemoteStationManager/$%ns3::%AarfcdWifiManager

         .
         .
         .

Attributes defined for this type:

    * SuccessK: Multiplication factor for the success threshold in the AARF algorithm.
  
        * Set with class: ns3::DoubleValue
        * Underlying type: double -1.79769e+308:1.79769e+308
        * Initial value: 2
        * Flags: construct write read 
   
    * TimerK: Multiplication factor for the timer threshold in the AARF algorithm.
  
        * Set with class: ns3::DoubleValue
        * Underlying type: double -1.79769e+308:1.79769e+308
        * Initial value: 2
        * Flags: construct write read 
   
         .
         .
         .

Attributes defined in parent class ns3::WifiRemoteStationManager:

    * IsLowLatency: If true, we attempt to modelize a so-called low-latency device: a device where decisions about tx parameters can be made on a per-packet basis and feedback about the transmission of each packet is obtained before sending the next. Otherwise, we modelize a  high-latency device, that is a device where we cannot update our decision about tx parameters after every packet transmission.
  
        * Set with class: BooleanValue
        * Underlying type: bool
        * Flags: read 
   
    * MaxSsrc: The maximum number of retransmission attempts for an RTS. This value will not have any effect on some rate control algorithms.
  
        * Set with class: ns3::UintegerValue
        * Underlying type: uint32_t 0:4294967295
        * Initial value: 7
        * Flags: construct write read 
   
         .
         .
         .

No TraceSources defined for this type.

TraceSources defined in parent class ns3::WifiRemoteStationManager:

    * MacTxRtsFailed: The transmission of a RTS by the MAC layer has failed

    * MacTxDataFailed: The transmission of a data packet by the MAC layer has failed

         .
         .
         .


===============================================================

static TypeId ns3::AarfWifiManager::GetTypeId (void)


         .
         .
         .


===============================================================

The list of all trace sources.

ns3::SimpleNetDevice

    * PhyRxDrop: Trace source indicating a packet has been dropped by the device during reception

ns3::Queue

    * Enqueue: Enqueue a packet in the queue.
    * Dequeue: Dequeue a packet from the queue.
    * Drop: Drop a packet stored in the queue.

         .
         .
         .


===============================================================

The list of all attributes.

ns3::ConfigStore

    * Mode: Configuration mode
    * Filename: The file where the configuration should be saved to or loaded from.
    * FileFormat: Type of file format

ns3::RealtimeSimulatorImpl

    * SynchronizationMode: What to do if the simulation cannot keep up with real time.
    * HardLimit: Maximum acceptable real-time jitter (used in conjunction with SynchronizationMode=HardLimit)

         .
         .
         .


===============================================================

The list of all global values.

    * GlobalValueRngSeed RngSeed: The global seed of all rng streams(1)
    * GlobalValueRngRun RngRun: The run number used to modify the global seed(1)
    * GlobalValueSimulatorImplementationType SimulatorImplementationType: The object class to use as the simulator implementation(ns3::DefaultSimulatorImpl)
    * GlobalValueSchedulerType SchedulerType: The object class to use as the scheduler implementation(ns3::MapScheduler)
    * GlobalValueChecksumEnabled ChecksumEnabled: A global switch to enable all checksums for all protocols(false)
Comment 9 Peter Barnes 2019-11-04 17:12:26 EST
Is this request now satisfied with 

$ ./waf --run "print-introspected-doxygen --output-text

Can we close this bug?
Comment 10 Tom Henderson 2019-11-04 20:39:35 EST
(In reply to Peter Barnes from comment #9)
> Is this request now satisfied with 
> 
> $ ./waf --run "print-introspected-doxygen --output-text
> 
> Can we close this bug?

I would like to suggest that we move to GitLab.com and make it a bit more useful.  --output-text is very verbose.

It might be a good starter C++ project (possibly even GCI).

What I had in mind is to be able to search on an object class name, without grepping this output.  For instance, I want the config path to the Txop object.

$ ./waf --run 'print-introspected-doxygen --output-text' | grep NodeList | grep Txop
    * "/NodeList/[i]/DeviceList/[i]/$ns3::WifiNetDevice/Mac/$ns3::RegularWifiMac/Txop/$ns3::QosTxop"
    * "/NodeList/[i]/DeviceList/[i]/$ns3::WifiNetDevice/Mac/$ns3::RegularWifiMac/VO_Txop"
    * "/NodeList/[i]/DeviceList/[i]/$ns3::WifiNetDevice/Mac/$ns3::RegularWifiMac/VI_Txop"
    * "/NodeList/[i]/DeviceList/[i]/$ns3::WifiNetDevice/Mac/$ns3::RegularWifiMac/BE_Txop"
    * "/NodeList/[i]/DeviceList/[i]/$ns3::WifiNetDevice/Mac/$ns3::RegularWifiMac/BK_Txop"
    * "/NodeList/[i]/DeviceList/[i]/$ns3::WifiNetDevice/Mac/$ns3::RegularWifiMac/Txop"
    * "/NodeList/[i]/DeviceList/[i]/$ns3::WifiNetDevice/Mac/$ns3::RegularWifiMac/Txop/Queue"

However, there may be gaps in this output.  For instance, TcpSocketBase is probably expected to be heavily searched, but is not in the output.  So we should probably audit the output against config store text output.

Plus, we should add to our documentation (tutorial and manual) about this capability before declaring it done.
Comment 11 Peter Barnes 2019-11-05 14:24:44 EST
Move to component documentation.
Comment 12 Peter Barnes 2019-11-25 17:25:30 EST
Looks to me like TcpSocketBase *is* in the output:

$ ./waf --run 'print-introspected-doxygen --output-text' | grep tcpsocketbase
        * Underlying type:  ns3::Ptr<  ns3::TcpSocketBase>
ns3::TcpSocketBase
ns3::TcpSocketBase is accessible through the following paths with Config::Set and Config::Connect:
%Callback signature: ns3::TcpSocketBase::TcpTxRxTracedCallback
%Callback signature: ns3::TcpSocketBase::TcpTxRxTracedCallback
ns3::TcpSocketBase
    * TcpSocketBase: src/internet/model/tcp-socket-base.cc
ns3::TcpSocketBase
Comment 13 Parth Pandya 2020-01-17 13:19:57 EST
Is this issue still active?
If yes, then what is expected to be done next?
Comment 14 Peter Barnes 2020-01-17 14:01:26 EST
@Parth Pandya: see Tom's comment #10 for his thoughts on what should be done next.
Comment 15 Parth Pandya 2020-01-22 22:37:27 EST
@Peter Barnes : Reading from the beginning it seems that @Mitch Watrous has done the changes to throw the output in the particular text-file. It also seems to me according to comment 10 that to reduce the orotundity of the cmd-line we can just add the grepping functionality in the program itself so that it reduces the verbosity and we can simple search on an object-class name to fetch the required output. Although not totally, but can reduce it a little.

But, before doing something may I please know how should your (@Tom Henderson) cmd-line should look like?
Comment 16 Peter Barnes 2020-02-03 14:47:38 EST
After off-list discussion, Tom and I agreed to split the remaining work in to two Gitlab issues, and mark this as RESOLVED MOVED.

The two new issues are

doc: p-i-d should have TypeId option
https://gitlab.com/nsnam/ns-3-dev/issues/140

core: CommandLine should show parent Attributes
https://gitlab.com/nsnam/ns-3-dev/issues/141