Life Before Templates

Recently functional languages are exploding on the scene. Old languages are slowly but steadily gaining new features. C++ 11 has a whole lot of new stuff. But, in this post I want to go back to some good old code. Code that was probably written when I was crawling as a toddler. C++ templates were introduced in mid-80s, so how did programmers code before that? Pre-processor

Have a look at http://docs.libreoffice.org/svl/html/svarray_8hxx.html It contains a lot of macros which create whole classes! (If you have time, see where each macro is being called, and do the whole stuff on your own to get the final class, and you'll appreciate the ingenuity of the programmers of old).

I have never used complex macros since in C and C++ since use of macros are kindaa frowned upon, so I decided to post a small and ugly use of these macros.

If I had been a programmer before C++ had templates, this is what I'd have done to add ;)

#define ADD_FUNC(ret,typedesc) \
typedesc add##ret(typedesc a, typedesc b){\
        typedesc c; \
        c = a + b; \
        return c;\
    }
The above code can be used by the following macro calls,
ADD_FUNC(int,int);
ADD_FUNC(float,float);

This would get me two neat functions for addition - addint(int,int), addfloat(float,float)

I can use these functions directly as,
cout<<addint(4,5)<<endl;
cout<<addfloat(4.3,5.2)<<endl;

Note that the above macro is very different from a normal macro function like,
#define MACRO_ADD(a,b) (a+b)

The first macro *creates new functions* which are then called directly by name. The second macro will be called differently,
cout<<macro_add(1,5)<<endl;
cout<<macro_add(2.2,3.1)<<endl;

Here is a full file to make everything very clear,

In LibreOffice code, you'll find that the calls to the macro generated functions/classes are themselves created using other macros. However all the old stuff is now being replaced by STL containers, so hurry you might miss some beautiful/ugly old code. (Its ugly in 2012, but it shows the ingenuity of the programmers of old! So that's the jackassery that was going on there!

So you clicked on the menu, huh?

Menu Dropdown




I put a breakpoint at libo/vcl/source/window/winproc.cxx:2405, at the case SAL_EVENTMOUSEDOWN, to see

what happens when I click a mouse. 




I clicked on File Menu, it hit the breakpoint. Then off it goes to calls ImplHandleSalMouseButtonDown () 

with the following details stored in pEvent and pWindow.




pEvent

    mnTime = 78764380 //Time

    mnX = 18 //x co-ordinate

    mnY = 9  //y co-ordinate

    mnButton = 1  //left button, 4 for right click, 2 for clicking with the scroller

    mnCode = 0  //to find whether click is part of some select etc.




pWindow - the window object.

    

The ImplHandleSalMouseButtonDown () function is in ./libo/vcl/source/window/winproc.cxx:2068, it checks

whether shift, ctrl or alt keys were pressed in 2076, and then calls ImplGetMouseButtonMode () with pEvent

(function is at ./libo/vcl/source/window/winproc.cxx:2030) to get further details of whether it is a simple

click event or whether it is part of select, multi (ctrl+click?) or range select, using pEvent's mnCode 

variable. 




The ImplGetMouseButtonMode () function returns nMode as 3. The first two if statements were true, ie.

MOUSE_SIMPLECLICK and MOUSE_SELECT. Once, this returns, ImplHandleSalMouseButtonDown () calls the function

ImplHandleMouseEvent (), with 




    - the window object - pWindow

    - nSVEvent = 1 (EVENT_MOUSEBUTTONDOWN)

    - bMouseLeave = False

    - x,y co-ordinates

    - time of the event nMsgTime

    - nCode = 1, to indicate status of shift,ctrl keys

    - and mode of click , nMode = 3




The function then does the following,

    - gets the details of the frame 

    - checks the previous location of the mouse. 

    - updates the frame data with the latest details 

    - checks whether the mouse has left or entered (?). 

    - finds the window

    - after finding the window 

        - it checks whether the window was disabled

    - it comes to line 666 (after several if conditions turned out to be false), for the mouse click event

        - here it checks for double click.

        - it then updates the details in the child window object

    - It creates the MouseEvent object at line 709

    - It notifies the child window of the event. Off to the next function.

    - In the next call, first the constructor of ImplDelData is called (maybe due to some 

        inheritance) ImplDelData::ImplDelData () at /home/jesso/Downloads/libreoffice/libo/vcl/inc/

        svdata.hxx:424, this is there to protect against the window from getting destroyed.

    - The NotifyEvent object is created.

    - It then checks whether it should bring the window into focus, if it previously didn't have focus,

        close context menus etc.

    - ImplCallPreNotify function

        - calls long Application::CallEventHooks () at ./libo/vcl/source/app/svapp.cxx:1657

        - that function returns 0

        - so it gets the PreNotify () method on the window object in the event object.

    - Finally it calls the MouseButtonDown() method on the pChild pointer, which happens to be 

          MenuBarWindow::MouseButtonDown () at ./libo/vcl/source/window/menu.cxx:5366




The MenuBarWindow::MouseButtonDown () then does the following,

    - It first finds the entry on which the action happened.

    - It then calls ChangeHighlightItem (which needs to be refactored, btw)

    - This decides whether to update the focus etc

    - It then finally creates the pop up in line 5477

So You Inserted A Table, huh?

Aim

To make sense of LibreOffice source code. I plan to put a breakpoint in the  constructors of SwTableBox, and then get the back trace to see the flow and gain a little understanding of what's going on. This is post is aimed at beginners, so a little knowledge of C++/Java should be able to get one through this.

A Little Background Info (Skip this)

I'm a programmer from the Center for Development of Advanced Computing (CDAC), India, currently on a joint project with King Abdulaziz City for Science and Technology, Saudi Arabia, tasked with fixing bugs/improving LibreOffice. This is part of my efforts to understand (and help my team-mates understand) the source code. Any comments/suggestions/edits to this will be GREATLY APPRECIATED ;) You can fork this at https://gist.github.com/3038116

Initial Steps

I started to debug LibreOffice by following the steps listed in the official debugging guide after creating a build with --enable-debug --enable-symbols set in autogen.sh

Starting the Debugger

I started soffice with ddd after sourcing ooenv. Next, I set a breakpoint in line 1717 and 1738, constructors of SwTableBox in the file libo/sw/source/core/table/swtable.cxx, by typing  break /home/jesso/Downloads/libreoffice/libo/sw/source/core/table/swtable.cxx:1717, at the GDB console in the bottom of the DDD window, hoping these lines would be executed when a new table was created, and clicked on Run to start the execution.

In Writer, I inserted a new table, and as expected, the breakpoint at 1717 was hit!  Clicking on Status -> Backtrace in ddd, opens a pop up window with the Backtrace. I am reproducing it below, skipping the memory addresses alone.

Backtrace

#36 in main () at main.c:24
#35 in sal_main () at main.c:25
#34 in soffice_main () at sofficemain.cxx:77
#33 in SVMain () at svmain.cxx:210
#32 in ImplSVMain () at svmain.cxx:173
#31 in desktop::Desktop::Main () at app.cxx:1764
#30 in Application::Execute () at svapp.cxx:414
#29 in Application::Yield () at svapp.cxx:469
#28 in ImplYield () at svapp.cxx:435
#27 in GtkInstance::Yield () at gtkinst.cxx:538
#26 in GtkData::Yield () at gtkdata.cxx:578
#25 in g_main_context_iteration () from libglib-2.0.so.0
#24 in ?? () from libglib-2.0.so.0
#23 in g_main_context_dispatch () from libglib-2.0.so.0
#22 in ?? from libglib-2.0.so.0
#21 in call_userEventFn () at gtkdata.cxx:950
#20 in GtkData::userEventFn () at gtkdata.cxx:940
#19 in SalGenericDisplay::DispatchInternalEvent () at gendisp.cxx:102
#18 in SalFrame::CallCallback () at salframe.hxx:281
#17 in ImplWindowFrameProc () at winproc.cxx:2575
#16 in ImplHandleUserEvent () at winproc.cxx:2003
#15 in Link::Call () at link.hxx:143
#14 in SfxHintPoster::LinkStubDoEvent_Impl () at hintpost.cxx:65
#13 in SfxHintPoster::DoEvent_Impl () at hintpost.cxx:61
#12 in SfxHintPoster::Event () at hintpost.cxx:71
#11 in GenLink::Call () at genlink.hxx:45
#10 in Link::Call () at link.hxx:143
#09 in SfxDispatcher::LinkStubPostMsgHandler () at dispatch.cxx:1215
#08 in SfxDispatcher::PostMsgHandler () at dispatch.cxx:1244
#07 in SfxDispatcher::Call_impl () at dispatch.cxx:259
#06 in SfxShell::CallExec () at shell.hxx:199
#05 in SfxStubSwTextShellExecInsert () at swslots.hxx:2376
#04 in SwTextShell::ExecInsert () at textsh.cxx:466
#03 in SwBaseShell::InsertTable () at baseh.cxx:2654
#02 in SwEditShell::InsertTable () at edtab.cxx:77
#01 in SwDoc::InsertTable () at ndtbl.cxx:545
#00 in SwTableBox::SwTableBox () at swtable.cxx:1717

So, that's 36 calls, but I guess only calls from #21 are related to my table insertion actions.

What happens in each call

I am skipping calls #36 - #25 for now as they are mostly related to application startup. Calls #25 - #22 are inside glib (so, i'm not going to bother much about them).

#25 g_main_context_iteration () from libglib-2.0.so.0

Checks whether any event sources are ready to be processed. More details can be found here.

#23 in g_main_context_dispatch () from libglib-2.0.so.0

This dispatches all sources. More details are here.

#21 in call_userEventFn () at gtkdata.cxx:950

It is called by g_main_context_dispatch () with a pointer to a generic pointer name data. I was unable to dereference it.

#20 in GtkData::userEventFn () at gtkdata.cxx:940

The generic data pointer becomes a GtkData pointer here. Displaying the value pointed to by the pointer reveals a SalGenericData object(?) containing a SalData object (?) and a m_pUserEvent pointer. Dereferencing the m_pUserEvent pointer I found it contained, pointers to callback_funcs, source_funcs, callback_data etc. All these are interesting but I am unable to dereference these now as they are still generic pointers. Well, on the GtkData pointer, GetGtkDisplay() method is called, which returns a GtkSalDisplay object, on which the DispatchInternalEvent() method is called (the method is inherited from SalGenericDisplay).

Note -
* pThis seems to be concerned with the data directly resulting from the event (?),
*pData seems to contain the general details of the whole parent window (?), getting it from the GetGenericData() call which returns the variable pImplSVData.

#19 in SalGenericDisplay::DispatchInternalEvent () at gendisp.cxx:102

Here the lock is acquired, to get the values from m_aUserEvents. So, this seems to be where the actual user event and the corresponding data are fetched (?). The nEvent value is 22. The SalFrame is obtained and the CallCallback method is called on this object.

#18 in SalFrame::CallCallback () at salframe.hxx:281

This just calls the function stored in its own m_pProc variable.

#17 in ImplWindowFrameProc () at winproc.cxx:2575 

This contains the message loop. This function seems to handle *all* the user's inputs on the LibreOffice window. Seems to be a gold mine for putting breakpoints when we don't have a clue about any bug, and then we can step from here to where we want! The nEvent = 22 is SALEVENT_USEREVENT. Off we go to the next call in the same file.

#16 in ImplHandleUserEvent () at winproc.cxx:1986 

This just calls the function stored in the pointer.

#15 in Link::Call () at link.hxx:143  

The function pointed to by the pointer is called. Printing pFunc we get
(PSTUB) 0xb758ebbe

#14 in SfxHintPoster::LinkStubDoEvent_Impl () at /libo/sfx2/source/notify/hintpost.cxx:56 

Simply passes the data along to the next function (?).

#13 in SfxHintPoster::DoEvent_Impl () at /libo/sfx2/source/notify/hintpost.cxx:52

It passes the pointer it received on to the next function.

#12 SfxHintPoster::Event () at hintpost.cxx:60

I guess now it comes directly here. Seems to pass a function pointer deeper down.

#11 GenLink::Call () at /libo/sfx2/inc/sfx2/genlink.hxx:45 - Calls the function pointer.

#10 Link::Call () at /libo/solver/unxlngi6.pro/inc/tools/link.hxx:143

We've come back (?) to Call #15. It took the else part in the previous call, and we're back. But now we are calling a different function.

Printing pFunc here -
(PSTUB) 0xb73d97ba

I guess this Link::Call seems to be used to resolve function pointers in general (?).

#09 SfxDispatcher::LinkStubPostMsgHandler () at /libo/sfx2/source/control/dispatch.cxx:1205 

This function is commented. (Yay!) Helper method to receive the asynchronously executed s.

#08 SfxDispatcher::PostMsgHandler () at /libo/sfx2/source/control/dispatch.cxx:1234 

Stuff is added to SfxSlotServer and the next call is made. Expanding the pSlot pointer variable in ddd shows the structure containing variables which have subsequent calls (SfxStubSwTextShellExecInsert) stored in them.

#07 in SfxDispatcher::Call_Impl () at /libo/sfx2/source/control/dispatch.cxx:249

Its a helper function to check whether a slot can be executed and check the execution itself (from the comments in the code). It passes the target function SfxStubSwTextShellExecInsert to method CallExec in class SfxShell.

#06 in SfxShell::CallExec () at /libo/sfx2/inc/sfx2/shell.hxx:190

It simply executes the function pointed to by the function pointer.

#05 in SfxStubSwTextShellExecInsert () at /libo/workdir/unxlngi6.pro/SdiTarget/sw/sdi/swslots.hxx:2376

Now you'll find a line SFX_EXEC_STUB(SwTextShell,ExecInsert). I spent some time grepping for that, so I'll reproduce that macro here. Btw, macro is defined in 'sfx2/inc/sfx2/msg.hxx'.
 
  #define SFX_EXEC_STUB( aShellClass, aExecMethod) \
  void SfxStub##aShellClass##aExecMethod( \
    SfxShell *pShell, SfxRequest& rReq) \
   { \
     (( aShellClass* ) pShell )->aExecMethod( rReq ); \
   }
 
IMHO, this file seems to be a gold mine for putting break points, because, like winproc.cxx in #17, all the control seems to flow through these two areas, but I'm not sure about putting breakpoints on macros (?).

#04 in SwTextShell::ExecInsert () at /libo/sw/source/ui/shells/textsh.cxx:466

The code is more understandable at these layers. This function seems to be concerned with the insertion of *all* the objects into the document (is the document itself called as the shell?). It has one huge switch case for handling the various types of objects that can be inserted. Talking about that, the function gets value of the slot from the SfxRequest variable that it received as an argument, whose value the  ddd is showing as 20330 (ie. variable nSlot=20330, of type unsigned short), that maps to FN_INSERT_TABLE.

How? These details are in /libo/clone/binfilter/binfilter/inc/bf_sw/cmdid.h, in line 349 we have FN_INSERT + 30, and line 38 has FN_INSERT = (SID_SW_START + 300), and SID_SW_START = 20000 (this is defined in /libo/binfilter/inc/bf_sfx2/sfxsids.hrc). So the question becomes, where did it calculate 20330 first, I have to look keenly in the upper layers and update :( . Inside the case, it simply calls
InsertTable function with the argument that it received.

#03 -> SwBaseShell::InsertTable () in libo/sw/source/ui/shells/baseh.cxx:2654

This is where all the options entered in the dialog are finally retrieved. The data is present in the _rRequest variable and you can notice the retrieval of the table name, number of rows and columns etc. in lines 2582 - 2586, using SFX_REQUEST_ARG macros. The values that are finally stored in pName, pRows etc. were all entered in the Table dialog box, and ddd displays the values as these are ordinary integers. The items are then added once again as to _rRequest in proper Sfx formats(?) in lines 2641 to 2644.

Finally at 2654, the table is inserted! Notice that this call is sandwiched between rSh.StartAllAction () and rSh.EndAllAction (). After this layer, the parameters are passed expicitly, that is, not packaged in SfxRequest object anymore.

#02 -> SwEditShell::InsertTable () at libo/sw/source/core/edit/edtab.cxx:77

Again all the contents of the function are sandwiched between StartAllAction () and EndAllAction (). The current position of the cursor is obtained from GetCrsr()->GetPoint(), and the GetDoc() function returns the current document object, on which the next call happens.

#01 -> SwDoc::InsertTable () in libo/sw/source/core/docnode/ndtbl.cxx

This seems to deal at the table level. It gets the boxes/cells from SwTableBox::SwTableBox () and stores it in the variable pBox. It then constructs the table and returns a table node (?) - the variable pNdTbl (of type SwTable).

#00 -> SwTableBox::SwTableBox () in libo/sw/source/core/table/swtable.cxx:1717 

This is where I put he break point blindly, well all the constructors in this class had one. This constructor gets called four times, that is, for each cell in the table (am I right about the cell -> box mapping?).

The journey isn't over yet, the damned table hasn't even been printed to the screen, and every single function has to return the data. I'll edit this again as I make my journey upwards all the way back!

Takeaways



Files in Calls #17 and #5 are great places to put break points when we have no idea about any bug etc. as they are the critical points through which the flow must happen. There seem to be a couple of important Get* functions like GetGenericData (), GetDoc (), GetCur () etc. which can be used to get important objects.

pImplSVData - seems to be an important variable, used to get the display etc (?). Get it using GetGenericData().


SwWrtShell Object
More details about that can be found here. It is used in many functions, and in each case is retrieved by using GetShell ().


SfxRequest Object

SfxRequest object seems to be a container through which the data are passed around generally.

* Items are added to it using, reqObj.AppendItem ( ).

* After all items are appended method Done() is called on the object. ie. reqObj.Done()

* Items are retrieved using SFX_REQUEST_ARG macro.
    - It is defined in libo/sfx2/inc/sfx2/request.hxx
    - #define SFX_REQUEST_ARG(rReq, pItem, ItemType, nSlotId, bDeep) \
        const ItemType *pItem = (const ItemType*)