Diagnostics tutorial
  1. Introduction
  2. Main classes
  3. Obtaining & using Diagnostics instances
  4. Obtaining & using Diagnosis instances
  5. Look-through Diagnosis
  6. Outro & todo list
<< | >>
 Obtaining & using Diagnostics instances

Diagnostics class is used to mark parts of code you want to analyse.

  1. Getting Diagnostics instance
  2. Beginning & ending work
  3. Marking code blocks for time measure
  4. Loop blocks

Getting Diagnostics instance

You can get instance with one of two constructors:
Diagnostics d= new Diagnostics();
Diagnostics d= new Diagnostics(true); //or false
Both statements means the same (clean constructor means the same as constructor with parameter true. This parameter tells you to use or not Garbage Collector while opening code blocks. Its useful in situations, when you want to find out how well your implementation works with smallest available processor and memory strain. If you need to find out how fast is your program in real conditions, you should pass false as parameter.

Beginning & ending work

Diagnostics has two methods called beginWork() and endWork().
Why should you use them?
Lets look at such a situation:
Diagnostics a= new Diagnostics();
a.startMeasuringTime();
...some actions - 1...
Diagnostics b=new Diagnostics();
...some actions - 2...
b.startMeasuringTime();
...some actions - 3...
a.stopMeasuringTime();
...some actions - 4...
b.stopMeasuringTime();

// methods start-/stopMeasuringTime() are not real Diagnostics methods! They are used to show example 
// of possible errors!
What can we see here?
Instance a measures time for "some actions" 1, 2 and 3, and time of creating instance b and calling b.startMeasuringTime().
Instance b measures time for "some actions"  3 and 4, and time of calling a.stopMeasuringTime().
Problem lies in measuring time for using other Diagnostics objects. It shouldnt be like this.
That is a moment where begin-/endWork() comes. Between calls for the same instance any use of different Diagnostics object will throw new DiagnosticsException("This Diagnostics instance is not working")  (or new DiagnosticsException("There is some working Diagnostics instance") if you try to use beginWork() for other instance than actually working).
DiagnosticsException inherites form RuntimeException, so you don't have to catch it. It won't occur if eveyrthing is marked OK, any instances are thrown if and only if you screw something up with beginning/ending work or marking blocks.

Marking code blocks for time measure

Now, when you have Diagnostics instance, after beginning work for it, you can mark code blocks to be measured.
It's quite easy. Lets say yo have something like this:
Diagnostics s=new Diagnostics();
d.beginWork();
And want to measure time of printing on default out stream words "Hello world".  You shall do as stands:
d.openBlock("Hello");
System.out.println("Hello world");
d.closeBlock("Hello");
Part of code between calls of openBlock(...) and closeBlock(...) with the same parameter is called block. For example above we have block "Hello". Parameters are used to differ blocks from each other, and are chosen arbitrally. As for now you can have the same block opened several times, if it have already been closed, but it's gonna change, and you will be forced to use different namesfor every block. See: Loop blocks
d.openBlock("A");
...
d.closeBlock("A");
...
d.openBlock("A");
...
d.closeBlock("A");
//as for now it's OK, but it's gonna change

d.openBlock("A");
...
//no closeBlock("A") here!
d.openBlock("A");

//it's gonna cause DiagnosticsException with message "A: This block is already opened"

d.openBlock("A");
...
d.closeBlock("A");
...
//no openBlock("A") here!
d.closeBlock("A");
//it's gonna cause Diagnostics Exception with message "A: This block is already closed"

d.openBlock("A");
...
d.closeBlock("A");
...
//no openBlock("B") here!
d.closeBlock("B");
//it's gonna cause Diagnostics Exception with message "B: This block haven't been opened"

You can nest blocks in each other, for example.
d.openBlock("A");
...
d.openBlock("B");
...
d.closeBlock("B");
...
d.closeBlock("A");
There is no limit how many times blocks may be nested. So below is correct:
d.openBlock("A");
...
d.openBlock("B");
...
d.openBlock("C");
...
d.openBlock("D");
...
d.openBlock("E");
...
d.closeBlock("E");
...
d.closeBlock("D");
...
d.closeBlock("C");
...
d.closeBlock("B");
...
d.closeBlock("A");
You don't have to worry about time of calling open/closeBlock("B") - it's gonna be cut from total time of block A.
It may look strange, but such a construct is right:
d.openBlock("A");
...
d.openBlock("B");
...
d.closeBlock("A");
...
d.closeBlock("B");
Time of calling openBlock("B") will be cut from block's A time, the same with calling closeBlock("A") form block's B time.

Loop blocks
Development of loop blocks is still in progress. As for now they are shown in Diagnosis as normal blocks. They should be used inside loops. What's the problem with loops? Why to create new kind of blocks just for them? It's easy. Lets have such a loop:
for (int i=0; i<3; i++)
	{
	d.openBlock("A");
	...
	d.closeBlock("A");
	}
It can be translated to:
int i=0;
d.openBlock("A");
...
d.closeBlock("A");
i++;
d.openBlock("A"):
...
d.closeBlock("A");
i++;
d.openBlock("A"):
...
d.closeBlock("A");
i++;
As we already know - in some time you won't be able to call several blocks with the same name. And other thing - when Diagnosis tells you that block A lasted for 100 ns, another A lasted for 12000ns and yet another for 12ns - how do you know in what order they happened?
Loop blocks are opened & closed with open-/closeLoopBlock(String, int). First parameter is name of block, but second one is variable connected with loop. In this case we should use openLoopBlock("A", i), but when using while or do...while you should create your own counter and pass it to loop block.
What is it used for? Each call of openLoopBlock(s, i) is alike to openBlock(s+"-LOOP-"+i) so that there will be no block with the same name.
Remember that int parameter should change AFTER closing block. Why? Lets have a look.
int i=0;
while (i<3)
	{
	d.openLoopBlock("A", i);
	i++;
	d.closeBlock("A", i);
	}
works as:
int i=0;
d.openBlock("A-LOOP-0");
i++; //i->1
d.closeBlock("A-LOOP-1");
d.openBlock("A-LOOP-1");
i++; //i->2
d.closeBlock("A-LOOP-2");
d.openBlock("A-LOOP-2");
i++; //i->3
d.closeBlock("A-LOOP-3");
Troubles that occurs are easy to spot - blocks are closed before they are opened.

Remember that only loopBlocks can be nested in other loopBlocks, but any block can be nested in standard block.

Tip:
Standard and Loop Blocks are represented with this same class, all difference is way of creating and naming them. So if you use in loop something like
loop_of_some_kind	//there is declared and changing i
	{
	d.openBlock("A-LOOP-"+i);
	...
	d.closeBlock("A-LOOP-"+i);
	}
Its gonna be treated the same way as using loopBlocks.