Friday, November 26, 2010

update to latest metauml

The metauml package contained in the default texlive installation on ubuntu is the old version 0.2.3. This version doesn't support component diagram. I have to update to latest version manually. Here is how:

  1. backup /usr/share/texmf-texlive/metapost/metauml
  2. download metauml here
  3. extract and copy everything under metauml/inputs to /usr/share/texmf-texlive/metapost/metauml
  4. run "sudo texhash" to refresh texmf database, so that new version will be recognized

Now try the following diagram, it should compile fine.
1 input metauml;
2   beginfig(1);
3
4   Component.C("ComponentAAA")();
5   drawObject(C);
6
7   endfig;
8 end

Tuesday, November 23, 2010

draw uml with latex&metauml

I've used and enjoyed the benefits of reversion control system for several years. RCS makes my life a lot easier. And it pushes me to highly prefer text format files over binary files, because text files can be managed by RCS more easily. metauml is a metapost library for creating uml diagrams, in text format.

Here are the steps to use it on ubuntu:
  1. install texlive with: sudo apt-get install texlive
  2. install metauml containing in metapost for tex: sudo apt-get install texlive-metapost
Texlive is also available for windows.
After all these tools have being installed, we can start our first uml diagram in latex.
Suppose we have following classes, and want to draw class diagram for them.
 1 class Point
 2 {
 3 public:
 4     int x;
 5     int y;
 6 };
 7 
 8 class Shape
 9 {
10     public:
11         virtual int get_circumference() = 0;
12         virtual ~shape();
13 };
14 
15 class Circle : public Shape
16 {
17     private:
18         Point center;
19         int radius;
20     public:
21         int get_circumference();
22 };


We create below metapost file, save it as class_diagram.mp, and use "mpost class_diagram.mp" command to generate a postscript file, class_diagram.1.
 1 input metauml;
 2 beginfig(1);
 3     %define classes
 4     Class.Point("Point")("+x: int""+y: int")();
 5     Class.Shape("Shape")()("+get_circumference(): int");
 6     Class.Circle("Circle")("-center: Point""-radius:  int")("+get_circumference(): int");
 7
 8     %layout classes
 9     topToBottom(50)(Point, Circle);
10     leftToRight(50)(Circle, Shape);
11 
12     %draw classes
13     drawObjects(Point, Shape, Circle);
14 
15     %link classes
16     link(inheritance)(Circle.e -- Shape.w);
17     link(composition)(Point.s -- Circle.n);
18 endfig;
19 end
20 

 Then we create below tex file as a container document for the postscript. And use "pdflatex uml.tex" to generate the final pdf file.
 1 \documentclass{article}
 2 
 3 % The following is needed in order to make the code compatible
 4 % with both latex/dvips and pdflatex.
 5 \ifx\pdftexversion\undefined
 6 \usepackage[dvips]{graphicx}
 7 \else
 8 \usepackage[pdftex]{graphicx}
 9 \DeclareGraphicsRule{*}{mps}{*}{}
10 \fi
11 
12 \title{MetaUML example}
13 \author{Raymond Wen}
14 
15 \begin{document}
16 
17 \maketitle
18 
19 \section{Example}
20 \includegraphics{class_diagram.1}
21 
22 \end{document}

A thing worth noticing is the latex document is of A4 size by default, which is not possible to contain a complex uml diagram. We can use "\paperwidth = 1024pt", "\paperheight = 1024pt", "\textheight = 800pt" command to create a document of arbitrary size. Here is more information about latex page layout.
The final diagram is shown below:

The advantages of using tex file to draw uml diagram includes:
  1. We can concentrate on the content of the uml, rather than its layout
  2. The diagram can be easily version controlled and compared
  3. It's easier to make modifications
  4. It's totally free
  5. The output file format can be easily changed
  6. It's possible to use/write tools to generate uml diagram automatically

Monday, November 15, 2010

avoid memory leak in osip

I was debugging memory leak bugs recently. The bug was caused by incorrect usage of the osip library. It's not uncommon that we meet problems when we rely on a library or framework that we don't fully understand.


Symptom and debugging
The symptom is our application ran more and more slowly, and eventually crashed. This seemed very likely to be caused by resource leak. And after ran performance monitor against our application, it's further confirmed that memory was leaking. The virtual bytes, private bytes of the process was continuously increasing.
With the help of umdh.exe, we can find out exact lines of code that were leaking memory. It showed all stack traces of currently allocated memory blocks (including blocks that were either being used or leaked, so we must identify which blocks were in use and which were not) at the moment of dumping.


Causes
The causes of the memory leak is mainly caused by not understanding below items well.

  • transaction isn't destroyed automatically
Osip doesn't take full responsibility of managing life time of transactions. Though osip invokes callbacks registered with osip_set_kill_transaction_callback when a transaction is to be terminated, the transaction isn't freed automatically. This is supposed to be done by osip users.
The first thought I had is to call osip_transaction_free inside the kill_transaction callback, but it was wrong. Because the transaction is still accessed after the kill_transaction callback returned. So, a possible point to free transactions is to do it at the end of an iteration of the main loop, after all events have been handled.
I just don't get why this important point isn't mentioned in the official document.
  • inconsistent resource management model
In osip, there are inconsistency between APIs about how memories are managed. For example, we call osip_message_set_body to set the body of a sip message, this function internally duplicates the string we passed to it. So, we can (and need to) free the string passed to it after the function finishes. But when we want to call osip_message_set_method, be cautious! This function doesn't duplicate the string passed in, instead, it simply references the string we gave it. So, we can't free the string which is now owned by the sip message.
Such inconsistency makes it extremely easy to get confused and write code that either crashes or leaks.