1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
|
<HTML>
<HEAD>
<TITLE>OpenMS concepts</TITLE>
<LINK HREF="doxygen.css" REL="stylesheet" TYPE="text/css">
<LINK HREF="style_ini.css" REL="stylesheet" TYPE="text/css">
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<A href="index.html">Home</A> ·
<A href="classes.html">Classes</A> ·
<A href="annotated.html">Annotated Classes</A> ·
<A href="modules.html">Modules</A> ·
<A href="functions_func.html">Members</A> ·
<A href="namespaces.html">Namespaces</A> ·
<A href="pages.html">Related Pages</A>
<HR style="height:1px; border:none; border-top:1px solid #c0c0c0;">
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title"><a class="el" href="namespaceOpenMS.html" title="Main OpenMS namespace. ">OpenMS</a> concepts </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This chapter covers some very basic concepts needed to understand OpenMS code. It describes OpenMS primitive types, namespaces, exceptions and important preprocessor macros. The classes described in this section can be found in the <em>CONCEPT</em> folder.</p>
<h1><a class="anchor" id="concept_primitives"></a>
Basic data types</h1>
<p>OpenMS has its own names for the C++ primitive types. The integer types of OpenMS are <em>Int</em> (int) and <em>UInt</em> (unsigned int). For floating point numbers, <em>Real</em> (float) and <em>DoubleReal</em> (double) are used.</p>
<p>These and more types are defined in <em><a class="el" href="Types_8h.html">OpenMS/CONCEPT/Types.h</a></em>. The <a class="el" href="namespaceOpenMS.html#a6f7145ffc251038582da541efc38a0d1" title="Returns the Type as as std::string. ">typeAsString()</a> function can be used to find out the actual type of an object, e.g. if typedefs are used.</p>
<h1><a class="anchor" id="concept_namespace"></a>
The OpenMS namespace</h1>
<p>The main classes of OpenMS are implemented in the namespace <em><a class="el" href="namespaceOpenMS.html" title="Main OpenMS namespace. ">OpenMS</a></em>. There are several sub-namespaces to the <em><a class="el" href="namespaceOpenMS.html" title="Main OpenMS namespace. ">OpenMS</a></em> namespace. The most important ones are:</p>
<ul>
<li><em><a class="el" href="namespaceOpenMS_1_1Constants.html" title="Mathematical and physical constants namespace. ">OpenMS::Constants</a></em> contains nature constants.</li>
<li><em><a class="el" href="namespaceOpenMS_1_1Math.html" title="Math namespace. ">OpenMS::Math</a></em> contains math functions and classes.</li>
<li><em><a class="el" href="namespaceOpenMS_1_1Exception.html" title="Exception namespace ">OpenMS::Exception</a></em> contains the OpenMS exceptions.</li>
<li><em><a class="el" href="namespaceOpenMS_1_1Internal.html" title="Namespace used to hide implementation details from users. ">OpenMS::Internal</a></em> contains certain auxiliary classes that are typically used by only one class of the <em><a class="el" href="namespaceOpenMS.html" title="Main OpenMS namespace. ">OpenMS</a></em> namespace and not by the user directly.</li>
</ul>
<p>There are several more namespaces. For a detailed description have a look at the class documentation.</p>
<h1><a class="anchor" id="concept_exceptions"></a>
Exception handling in OpenMS</h1>
<p>All exceptions are defined in the namespace <em><a class="el" href="namespaceOpenMS_1_1Exception.html" title="Exception namespace ">OpenMS::Exception</a></em>. The Base class for all OpenMS exceptions is <em>Base</em>. This base class provides three members for storing the source file, the line number and the function name where the exception occurred. All derived exceptions provide a constructor that takes at least these arguments. The following code snippet shows the handling of an index overflow: </p>
<div class="fragment"><div class="line"><span class="comment">// header</span></div>
<div class="line"><span class="comment"></span><span class="keywordtype">void</span> someMethod(<a class="code" href="group__Concept.html#gaba0996d26f7be2572973245b51852757">UInt</a> index);</div>
<div class="line"></div>
<div class="line"><span class="comment">// C file</span></div>
<div class="line"> <span class="keywordtype">void</span> someMethod(<a class="code" href="group__Concept.html#gaba0996d26f7be2572973245b51852757">UInt</a> index) </div>
<div class="line"> {</div>
<div class="line"> <span class="keywordflow">if</span> (index >= size())</div>
<div class="line"> {</div>
<div class="line"> <span class="keywordflow">throw</span> Exception::IndexOverflow(__FILE__, __LINE__, __PRETTY_FUNCTION__, index, size()-1);</div>
<div class="line"> }</div>
<div class="line"> <span class="comment">// do something</span></div>
<div class="line"> };</div>
</div><!-- fragment --><p> Note the first three arguments given to the constructor: <em>__FILE__</em> and <em>__LINE__</em> are built-in preprocessor macros that hold the file name and the line number. <em>__PRETTY_FUNCTION__</em> is replaced by the GNU g++ compiler with the demangled name of the current function (including the class name and argument types). For other compilers we define it as "<unknown>". For an index overflow exception, there are two further arguments: the invalid index and the maximum allowed index.</p>
<p>The file name, line number and function name are very useful in debugging. However, OpenMS also implements its own exception handler which allows to turn each uncaught exception into a segmentation fault. With gcc this mechanism allows developers to trace the source of an exception with a debugger more effectively. To use this feature, set the environment variable <em>OPENMS_DUMP_CORE</em>. For Visual Studio you should set a breakpoint in GlobalExceptionHandler::newHandler() in Exception.C, otherwise you might loose the stacktrace to pinpoint the inital exception.</p>
<h1><a class="anchor" id="concept_macros"></a>
Condition macros</h1>
<p>In order to enforce algorithmic invariants, the two preprocessor macros <em>OPENMS_PRECONDITION</em> and <em>OPENMS_POSTCONDITION</em> are provided. These macros are enabled only if debug info is enabled and optimization is disabled in <em>cmake</em>. Otherwise they are removed by the preprocessor, so they won't cost any performance.</p>
<p>The macros throw Exception::Precondition or Exception::Postcondition respectively if the condition fails. The example from section <a class="el" href="tutorial_concept.html#concept_exceptions">Exception handling in OpenMS</a> could have been implemented like that: </p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> someMethod(<a class="code" href="group__Concept.html#gaba0996d26f7be2572973245b51852757">UInt</a> index)</div>
<div class="line">{</div>
<div class="line"> <a class="code" href="group__Conditions.html#ga45a74ea28109e7e1ed992fbd2ee97778">OPENMS_PRECONDITION</a>(index < size(),<span class="stringliteral">"Precondition not met!"</span>);</div>
<div class="line"> <span class="comment">//do something</span></div>
<div class="line">};</div>
</div><!-- fragment --> </div></div><!-- contents -->
<HR style="height:1px; border:none; border-top:1px solid #c0c0c0;">
<TABLE width="100%" border="0">
<TR>
<TD><font color="#c0c0c0">OpenMS / TOPP release 1.11.1</font></TD>
<TD align="right"><font color="#c0c0c0">Documentation generated on Thu Nov 14 2013 11:19:24 using doxygen 1.8.5</font></TD>
</TR>
</TABLE>
</BODY>
</HTML>
|
