Tutorial: Asserts.Asserts.Everywhere!

Got a ReactOS tutorial to share? Drop it in here

Moderator: Moderator Team

Post Reply
vicmarcal
Test Team
Posts: 2733
Joined: Mon Jul 07, 2008 12:35 pm

Tutorial: Asserts.Asserts.Everywhere!

Post by vicmarcal »

***Level: Beginner***

In this small tutorial I will try to explain what an ASSERT is.
This is a Beginner guide, so feel free to jump to the section you want to read.

What is an Assertion?
An Assert is just a check introduced by the developer with just one objective: Stop the code running when a bug has been found.

The DetectFreeSize function.Understanding C a little.
This function doesn't exist in ReactOS.It's just a simple example:
//Free Disk Size

Code: Select all

float DetectFreeSize(float TotalDiskSize, float UsedDiskSize)
{
//We receive the TotalDiskSize and the UsedDiskSize
float FreeSize;
//We store the value in FreeSize.
FreeSize=TotalDiskSize-UsedDiskSize;
//We return the value of FreeSize
return FreeSize;
}
This (really) stupid function recives 2 parameters( TotalDiskSize and UsedDiskSize) and it returns the FreeSize.
A call to this function could be:
DetectFreeSize (8,2)
This means that we are calling the previously defined "DetectFreeSize function" with 2 parameters: The first one (the 8) is assigned to the "TotalDiskSize" variable, while the second one (the 2) is assigned to the "UsedDiskSize" one.
The function then can be understood in this particular case as:

Code: Select all

float DetectFreeSize(float TotalDiskSize, float UsedDiskSize)
{
//We receive a TotalDiskSize(8) and a UsedDiskSize(2)
float FreeSize;
//We store the value of the subtraction in FreeSize
FreeSize=TotalDiskSize-UsedDiskSize; //FreeSize=8-2
//We return the value of FreeSize(6)
return FreeSize;
}
So the function is returning a value "6" in this particular case. What is done with that returned value is out of the scope right now.A function is just that: A "machine" that produces an output when one or several other variables goes into.
In this case the machine(*cough* function) produces and returns "FreeSize" when "TotalDiskSize" and "UsedDiskSize" are inputs.

TotalDiskSize--------->|***********|
,,,,,,,,,,,,,,,,,,,,,,,,,,| Machine |--------->FreeSize
UsedDiskSize--------->|________|



Adding an ASSERTION to DetectFreeSize function

Something obvious is that TotalDiskSize can't be never 0. (Unless you are using a new E.T. technology that you should release under GPL then).
But in an Alpha software EVERYTHING can happen so we will politely add an ASSERT.
An ASSERT must be created this way:
ASSERT[THE_CONDITION_THAT_SHOULD_HAPPEN_NORMALLY]
This means: Stop the execution when THE_CONDITION_THAT_SHOULD_HAPPEN_NORMALLY does NOT happen.
Has sense isn't it?
Easier to see with this example:
It's really important that TotalDiskSize !=0 so this is THE_CONDITION_THAT_SHOULD_HAPPEN_NORMALLY.
So the Assert will be:
ASSERT[TotalDiskSize!=0]


So let's add the new ASSERT:

Code: Select all

float DetectFreeSize(float TotalDiskSize, float UsedDiskSize)
{
//We receive the TotalDiskSize and the UsedDiskSize
ASSERT[TotalDiskSize!=0] //It's really important that TotalDisk!=0
float FreeSize;
//We store the value in FreeSize.
FreeSize=TotalDiskSize-UsedDiskSize;
//We return the value of FreeSize
return FreeSize;
}
Hitting an Assertion
How do we know that we have hit an Assertion? Just looking the debuglog.
You will see a line in the debuglog as follows:
Assertion 'TotalDiskSize!=0' failed at path/to/file/where/the/function/is/defined.c line 8
Now you have just to go to that specific line, in that specific file and you will find something like:
ASSERT[TotalDiskSize!=0] //It's really important that TotalDisk!=0 .

What does an Assertion reveal?
It can reveal 2 kind of problems.
1)A bug when calculating TotalDiskSize. As we expect TotalDiskSize being !=0 and the value is ==0 then TotalDiskSize was wrongly calculated.
2)A wrong ASSERT. Usually MSDN, the Microsoft API-Functions reference, has some typos and it could lead to wrong ASSERTs. Imagine that it says that Windows can't manage HDD of 666GB because it's a nasty number and the dev adds an ASSERT(TotalDiskSize!=0 && TotalDiskSize!=666); obviously an HDD of 666GB,if any, will Assert with no reason.

Usually 1) is the most commun thing. So your debuglog is exposing a BUG.

Why an Assertion is such important?
The Assert is pointing DIRECTLY to the buggy variable. And having the buggy variable you have almost all ;).A dev can easily track the variable and find where the bug is.Even a tester, without any knowledge of the code, can track it down.
Good developers uses the ASSERT a lot, as it helps to find where the problem is in an easy way without losing time. Testers can even help to hunt it.

Can I force to continue the execution?
Yes sure.Under your total reponsability.
If the Dev have added an Assertion there, it means that it's an important requirement that should be met.
If you think the ASSERT is wrong, or that it won't affect the app a lot,then just type "CONT" and ReactOS will continue the execution using, of course, the wrong variable.


The CONDITION_THAT_SHOULD_HAPPEN_NORMALLY is long and hard to evaluate

There is a Math way for crazy people.
An ASSERT can be seen as an IF (FALSE).
I try to avoid this logical procedure as it makes me madthe brain is structured for IF(TRUE)not for IF(FALSE) but the following trick is really useful for long and hard CONDITION_THAT_SHOULD_HAPPEN_NORMALLY.

Code: Select all

IF (!THE_CONDITION_THAT_SHOULD_HAPPEN_NORMALLY)/*Look at the !, this is used to force the IF(FALSE) to be an IF(TRUE) */
{ 
HALT_EXECUTION;
}else CONTINUE_NORMALLY_THE_EXECUTION
Usually the ASSERTS aren't such hard, as they are used to see in a fast sight where the problem is, so I didn't have to deal with these kinds of conditions many times(luckily).
wildschwein
Posts: 420
Joined: Tue Sep 16, 2008 1:13 pm

Re: Tutorial: Asserts.Asserts.Everywhere!

Post by wildschwein »

Wow, you hold your promise, awsome great !

I must study this and read it precisely....

Please write more such tutorials to get testers more in the internas of ros....
Post Reply

Who is online

Users browsing this forum: No registered users and 10 guests