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
#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*)
No comments:
Post a Comment