Browse code

added more documentation to libraries and some cosmetic changes needed by doc

Vaclav Kubart authored on 08/11/2005 14:45:09
Showing 52 changed files
... ...
@@ -1,14 +1,13 @@
1 1
 <?xml version="1.0" encoding="UTF-8"?>
2 2
 
3 3
 <!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'
4
-'file:///usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd'>
5
-
6
-<!--<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'
7
-'http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd'>-->
4
+'http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd'[
5
+	<!ENTITY % local.common.attrib "xml:base  CDATA  #IMPLIED">
6
+]>
8 7
 
9 8
 <book lang="en">
10 9
 <bookinfo>
11
-	<title>Common Data Structures</title>
10
+	<title>Common Data Structures (libcds)</title>
12 11
 	<author><firstname>Václav</firstname><surname>Kubart</surname></author>
13 12
 	<abstract><para>Description of CDS (Common Data Structures) library.
14 13
 	</para></abstract>
... ...
@@ -35,11 +34,20 @@ is able to use some internal SER's data types like strings.
35 34
 </para>
36 35
 </section>
37 36
 
37
+<section id="libcds.dependencies"><title>Dependencies</title>
38
+<para>This library depends only on standard C libraries and needs no other
39
+external libraries.</para>
40
+</section>
41
+
38 42
 </preface>
39 43
 
40
-<!--<part><title>Functions and data types</title>-->
44
+<part><title>Reference</title>
45
+<include xmlns="http://www.w3.org/2001/XInclude" href="memory.xml"/>
41 46
 <include xmlns="http://www.w3.org/2001/XInclude" href="sstr.xml"/>
42 47
 <include xmlns="http://www.w3.org/2001/XInclude" href="dstring.xml"/>
43 48
 <include xmlns="http://www.w3.org/2001/XInclude" href="serialization.xml"/>
44
-<!--</part>-->
49
+<include xmlns="http://www.w3.org/2001/XInclude" href="sync.xml"/>
50
+<include xmlns="http://www.w3.org/2001/XInclude" href="msg_queue.xml"/>
51
+</part>
52
+
45 53
 </book>
46 54
new file mode 100644
... ...
@@ -0,0 +1,50 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="cds_free"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>cds_free</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>cds_free</refname> <!-- function name -->
14
+<refpurpose>free allocated memory</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/memory.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>void <function>cds_free</function></funcdef>
24
+  <paramdef>void *<parameter>ptr</parameter></paramdef>
25
+</funcprototype>
26
+
27
+</funcsynopsis></refsynopsisdiv>
28
+
29
+<refsect1><title>Description</title>
30
+<para>Frees memory allocated using <function>cds_malloc</function>.
31
+<!-- detailed description -->
32
+</para>
33
+
34
+</refsect1>
35
+
36
+<refsect1><title>Return value</title>
37
+<para>
38
+<!-- return value description -->
39
+Returns 0 on success, non-zero on error.
40
+</para>
41
+</refsect1>
42
+
43
+<refsect1><title>See Also</title>
44
+<para>
45
+<!-- references to other pages -->
46
+</para>
47
+</refsect1>
48
+
49
+</refentry> 
50
+
0 51
new file mode 100644
... ...
@@ -0,0 +1,52 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="cds_malloc"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>cds_malloc</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>cds_malloc</refname> <!-- function name -->
14
+<refpurpose>memory allocation</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/memory.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>int <function>cds_malloc</function></funcdef>
24
+  <paramdef>int <parameter>size</parameter></paramdef>
25
+</funcprototype>
26
+
27
+</funcsynopsis></refsynopsisdiv>
28
+
29
+<refsect1><title>Description</title>
30
+<para>Allocates Memory of given size. If compiled with SER it internaly uses
31
+<function>shm_malloc</function>, if compiled without SER it uses 
32
+<function>malloc</function>.
33
+<!-- detailed description -->
34
+</para>
35
+
36
+</refsect1>
37
+
38
+<refsect1><title>Return value</title>
39
+<para>Returns NULL on error, pointer to allocated memory otherwise.
40
+<!-- return value description -->
41
+</para>
42
+</refsect1>
43
+
44
+<refsect1><title>See Also</title>
45
+<para>
46
+<xref linkend="cds_malloc"/>
47
+<!-- references to other pages -->
48
+</para>
49
+</refsect1>
50
+
51
+</refentry> 
52
+
0 53
new file mode 100644
... ...
@@ -0,0 +1,46 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="cds_mutex_destroy"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>cds_mutex_destroy</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>cds_mutex_destroy</refname> <!-- function name -->
14
+<refpurpose>mutex destruction</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/sync.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>int <function>cds_mutex_destroy</function></funcdef>
24
+  <paramdef>cds_mutex_t *<parameter>m</parameter></paramdef>
25
+</funcprototype>
26
+
27
+</funcsynopsis></refsynopsisdiv>
28
+
29
+<refsect1><title>Description</title>
30
+<para>Destroys mutex. It is defined as macro now thus type control and return
31
+value specification may be problematic!
32
+<!-- detailed description -->
33
+</para>
34
+
35
+</refsect1>
36
+
37
+<refsect1><title>See Also</title>
38
+<para>
39
+<!-- references to other pages -->
40
+<xref linkend="cds_mutex_t"/>, <xref linkend="cds_mutex_init"/>,
41
+<xref linkend="cds_mutex_lock"/>, <xref linkend="cds_mutex_unlock"/>
42
+</para>
43
+</refsect1>
44
+
45
+</refentry> 
46
+
0 47
new file mode 100644
... ...
@@ -0,0 +1,45 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="cds_mutex_init"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>cds_mutex_init</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>cds_mutex_init</refname> <!-- function name -->
14
+<refpurpose>mutex initialization</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/sync.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>int <function>cds_mutex_init</function></funcdef>
24
+  <paramdef>cds_mutex_t *<parameter>m</parameter></paramdef>
25
+</funcprototype>
26
+
27
+</funcsynopsis></refsynopsisdiv>
28
+
29
+<refsect1><title>Description</title>
30
+<para>Initializes mutex. It is defined as macro now thus type control and return
31
+value specification may be problematic!
32
+<!-- detailed description -->
33
+</para>
34
+
35
+</refsect1>
36
+
37
+<refsect1><title>See Also</title>
38
+<!-- references to other pages -->
39
+<para><xref linkend="cds_mutex_t"/>, <xref linkend="cds_mutex_destroy"/>,
40
+<xref linkend="cds_mutex_lock"/>, <xref linkend="cds_mutex_unlock"/>
41
+</para>
42
+</refsect1>
43
+
44
+</refentry> 
45
+
0 46
new file mode 100644
... ...
@@ -0,0 +1,46 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="cds_mutex_lock"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>cds_mutex_lock</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>cds_mutex_lock</refname> <!-- function name -->
14
+<refpurpose>mutex lock</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/sync.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>int <function>cds_mutex_lock</function></funcdef>
24
+  <paramdef>cds_mutex_t *<parameter>m</parameter></paramdef>
25
+</funcprototype>
26
+
27
+</funcsynopsis></refsynopsisdiv>
28
+
29
+<refsect1><title>Description</title>
30
+<para>Locks mutex. It is defined as macro now thus type control and return
31
+value specification may be problematic!
32
+<!-- detailed description -->
33
+</para>
34
+
35
+</refsect1>
36
+
37
+<refsect1><title>See Also</title>
38
+<para>
39
+<!-- references to other pages -->
40
+<xref linkend="cds_mutex_t"/>, <xref linkend="cds_mutex_init"/>,
41
+<xref linkend="cds_mutex_destroy"/>, <xref linkend="cds_mutex_unlock"/>
42
+</para>
43
+</refsect1>
44
+
45
+</refentry> 
46
+
0 47
new file mode 100644
... ...
@@ -0,0 +1,41 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="cds_mutex_t">
7
+
8
+<refmeta><refentrytitle>cds_mutex_t</refentrytitle>
9
+<manvolnum>3</manvolnum></refmeta>
10
+
11
+<refnamediv><refname>cds_mutex_t</refname>
12
+<refpurpose>wrapper type for mutex</refpurpose>
13
+</refnamediv>
14
+
15
+<refsynopsisdiv><synopsis>
16
+#include &lt;cds/sync.h&gt;
17
+
18
+outside of SIP Express Router:
19
+
20
+#include &lt;pthread.h&gt;
21
+#define cds_mutex_t   pthread_mutex_t
22
+
23
+inside of SIP Express Router:
24
+
25
+#define cds_mutex_t   gen_lock_t
26
+
27
+</synopsis></refsynopsisdiv>
28
+
29
+<refsect1><title>Description</title>
30
+<para>Wrapper type for mutex. It is defined as macro now, but this may change.
31
+</para> 
32
+</refsect1>
33
+
34
+<refsect1><title>See Also</title>
35
+<para><xref linkend="cds_mutex_init"/>, <xref linkend="cds_mutex_destroy"/>,
36
+<xref linkend="cds_mutex_lock"/>, <xref linkend="cds_mutex_unlock"/>
37
+</para>
38
+</refsect1>
39
+
40
+</refentry> 
41
+
0 42
new file mode 100644
... ...
@@ -0,0 +1,46 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="cds_mutex_unlock"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>cds_mutex_unlock</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>cds_mutex_unlock</refname> <!-- function name -->
14
+<refpurpose>mutex unlock</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/sync.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>int <function>cds_mutex_unlock</function></funcdef>
24
+  <paramdef>cds_mutex_t *<parameter>m</parameter></paramdef>
25
+</funcprototype>
26
+
27
+</funcsynopsis></refsynopsisdiv>
28
+
29
+<refsect1><title>Description</title>
30
+<para>Unlocks mutex. It is defined as macro now thus type control and return
31
+value specification may be problematic!
32
+<!-- detailed description -->
33
+</para>
34
+
35
+</refsect1>
36
+
37
+<refsect1><title>See Also</title>
38
+<para>
39
+<!-- references to other pages -->
40
+<xref linkend="cds_mutex_t"/>, <xref linkend="cds_mutex_init"/>,
41
+<xref linkend="cds_mutex_destroy"/>, <xref linkend="cds_mutex_lock"/>
42
+</para>
43
+</refsect1>
44
+
45
+</refentry> 
46
+
0 47
new file mode 100644
... ...
@@ -0,0 +1,64 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="create_message"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>create_message</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>create_message</refname> <!-- function name -->
14
+<refpurpose>allocates and initializes message</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/msg_queue.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>int <function>create_message</function></funcdef>
24
+  <paramdef>void *<parameter>data</parameter></paramdef>
25
+  <paramdef>int <parameter>data_len</parameter></paramdef>
26
+</funcprototype>
27
+
28
+</funcsynopsis></refsynopsisdiv>
29
+
30
+<refsect1><title>Description</title>
31
+
32
+<para>Allocates message using <function>cds_malloc</function> and initializes
33
+its content so it will be freed automaticaly. Pointer to the explicitly
34
+allocated data is set to <parameter>data</parameter> and its length is set to
35
+<parameter>data_len</parameter>. Message created by <function>create_message</function> 
36
+should be freed using <function>message_free</function>.</para>
37
+
38
+<para>Unremoved messages created this way are freed automaticaly in
39
+<function>msg_queue_destroy</function> using <function>free_message</function>.
40
+</para>
41
+
42
+<para>Calling <function>free_message</function> to such message frees the
43
+message and the data given by parameter <parameter>data</parameter> too, thus
44
+they can NOT be freed by the caller!
45
+</para>
46
+
47
+</refsect1>
48
+
49
+<refsect1><title>Return value</title>
50
+<para>
51
+<!-- return value description -->
52
+Returns NULL on error, pointer to initialized message structure otherwise.
53
+</para>
54
+</refsect1>
55
+
56
+<refsect1><title>See Also</title>
57
+<para>
58
+<xref linkend="create_message_ex"/>, <xref linkend="init_message_ex"/>
59
+<!-- references to other pages -->
60
+</para>
61
+</refsect1>
62
+
63
+</refentry> 
64
+
0 65
new file mode 100644
... ...
@@ -0,0 +1,63 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="create_message_ex"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>create_message_ex</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>create_message_ex</refname> <!-- function name -->
14
+<refpurpose>create and initialize message</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/msg_queue.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>mq_message_t *<function>create_message_ex</function></funcdef>
24
+  <paramdef>int <parameter>data_len</parameter></paramdef>
25
+</funcprototype>
26
+
27
+</funcsynopsis></refsynopsisdiv>
28
+
29
+<refsect1><title>Description</title>
30
+
31
+<para>Allocates message with data of given size
32
+(<parameter>data_len</parameter>) using <function>cds_malloc</function>. It
33
+initializes message content so it will be freed automaticaly. 
34
+Pointer to allocated data should be obtained by 
35
+<function>get_message_data</function>.
36
+</para>
37
+
38
+<para>Messages created by <function>create_message_ex</function> 
39
+should be freed using <function>message_free</function>.</para>
40
+
41
+<para>Unremoved messages created this way are freed automaticaly in
42
+<function>msg_queue_destroy</function> using <function>free_message</function>.
43
+</para>
44
+
45
+
46
+</refsect1>
47
+
48
+<refsect1><title>Return value</title>
49
+<para>
50
+<!-- return value description -->
51
+Returns NULL on error, pointer to initialized message structure otherwise.
52
+</para>
53
+</refsect1>
54
+
55
+<refsect1><title>See Also</title>
56
+<para>
57
+<xref linkend="create_message"/>, <xref linkend="init_message_ex"/>
58
+<!-- references to other pages -->
59
+</para>
60
+</refsect1>
61
+
62
+</refentry> 
63
+
0 64
new file mode 100644
... ...
@@ -0,0 +1,49 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="destroy_sstream"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>destroy_sstream</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>destroy_sstream</refname> <!-- function name -->
14
+<refpurpose>destroys input/output serialization stream</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/serialize.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>void <function>destroy_sstream</function></funcdef>
24
+  <paramdef>sstream_t *<parameter>ss</parameter></paramdef>
25
+</funcprototype>
26
+
27
+</funcsynopsis></refsynopsisdiv>
28
+
29
+<refsect1><title>Description</title>
30
+<para>
31
+Destroys serialization stream and frees all internal data buffers. After calling
32
+this function can NOT be called any other serialization stream manipulation
33
+function except <function>init_input_sstream</function> or
34
+<function>init_ouput_stream</function>.
35
+<!-- detailed description -->
36
+</para>
37
+
38
+</refsect1>
39
+
40
+<refsect1><title>See Also</title>
41
+<para>
42
+<xref linkend="sstream_t"/>, <xref linkend="init_input_sstream"/>, <xref
43
+linkend="init_output_sstream"/>
44
+<!-- references to other pages -->
45
+</para>
46
+</refsect1>
47
+
48
+</refentry> 
49
+
0 50
new file mode 100644
... ...
@@ -0,0 +1,57 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="free_message"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>free_message</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>free_message</refname> <!-- function name -->
14
+<refpurpose>free message</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/msg_queue.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>void <function>free_message</function></funcdef>
24
+  <paramdef>mq_message_t *<parameter>msg</parameter></paramdef>
25
+</funcprototype>
26
+
27
+</funcsynopsis></refsynopsisdiv>
28
+
29
+<refsect1><title>Description</title>
30
+<para>Frees message. If data is allocated explicitly it frees it using
31
+<function>cds_free</function>,
32
+if they are allocated implicitly, it is freed together with message. Thus simple
33
+data strutures are deallocated automaticaly in both cases. There might be a
34
+problem with more complicated structures with internal pointers to other
35
+structures - these are NOT deallocated automaticaly because this function can't
36
+know the internal data structure and they must be freed by the
37
+caller!
38
+<!-- detailed description -->
39
+</para>
40
+
41
+<para>This function does NOT free messages which were initialized using
42
+<function>message_init_ex</function> with <parameter>auto_free</parameter> not
43
+set, they must be freed explicitly by caller!
44
+</para>
45
+
46
+</refsect1>
47
+
48
+<refsect1><title>See Also</title>
49
+<para>
50
+<xref linkend="create_message"/>, <xref linkend="create_message_ex"/>, <xref
51
+linkend="init_message_ex"/>
52
+<!-- references to other pages -->
53
+</para>
54
+</refsect1>
55
+
56
+</refentry> 
57
+
0 58
new file mode 100644
... ...
@@ -0,0 +1,55 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="get_serialized_sstream"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>get_serialized_sstream</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>get_serialized_sstream</refname> <!-- function name -->
14
+<refpurpose>get output stream data</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/serialize.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>int <function>get_serialized_sstream</function></funcdef>
24
+  <paramdef>sstream_t *<parameter>ss</parameter></paramdef>
25
+  <paramdef>str_t *<parameter>dst</parameter></paramdef>
26
+</funcprototype>
27
+
28
+</funcsynopsis></refsynopsisdiv>
29
+
30
+<refsect1><title>Description</title>
31
+<para>
32
+Copies data stored during output serialization into given destination. It allocates buffer
33
+necessary for serialized data using cds_malloc function. These data can be freed
34
+using <function>str_free_content</function>.
35
+<!-- detailed description -->
36
+</para>
37
+
38
+</refsect1>
39
+
40
+<refsect1><title>Return value</title>
41
+<para>
42
+<!-- return value description -->
43
+Returns 0 on success, non-zero on error.
44
+</para>
45
+</refsect1>
46
+
47
+<refsect1><title>See Also</title>
48
+<para>
49
+<xref linkend="sstream_t"/>, <xref linkend="str_free_content"/>
50
+<!-- references to other pages -->
51
+</para>
52
+</refsect1>
53
+
54
+</refentry> 
55
+
0 56
new file mode 100644
... ...
@@ -0,0 +1,56 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="init_input_sstream"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>init_input_sstream</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>init_input_sstream</refname> <!-- function name -->
14
+<refpurpose>initializes input serialization stream</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis> <!-- usage -->
18
+
19
+<funcsynopsisinfo>
20
+#include &lt;cds/serialize.h&gt; <!-- included headers -->
21
+</funcsynopsisinfo>
22
+
23
+<funcprototype> <!-- function prototype -->
24
+  <funcdef>int <function>init_input_sstream</function></funcdef>
25
+  <paramdef>sstream_t *<parameter>ss</parameter></paramdef>
26
+  <paramdef>char *<parameter>data_in</parameter></paramdef>
27
+  <paramdef>int <parameter>data_len</parameter></paramdef>
28
+</funcprototype>
29
+
30
+</funcsynopsis></refsynopsisdiv>
31
+
32
+<refsect1><title>Description</title>
33
+<para>Initializes serialization stream as input. Input data are read from char
34
+array given by pointer <parameter>data_in</parameter> and length
35
+<parameter>data_len</parameter>.
36
+<!-- detailed description -->
37
+</para>
38
+
39
+</refsect1>
40
+
41
+<refsect1><title>Return value</title>
42
+<para>
43
+Returns 0 if successful, nonzero otherwise.
44
+<!-- return value description -->
45
+</para>
46
+</refsect1>
47
+
48
+<refsect1><title>See Also</title>
49
+<para>
50
+<xref linkend="sstream_t"/>
51
+<!-- references to other pages -->
52
+</para>
53
+</refsect1>
54
+
55
+</refentry> 
56
+
0 57
new file mode 100644
... ...
@@ -0,0 +1,53 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="init_message_ex"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>init_message_ex</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>init_message_ex</refname> <!-- function name -->
14
+<refpurpose>initialize message</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/msg_queue.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>void <function>init_message_ex</function></funcdef>
24
+  <paramdef>mq_message_t *<parameter>m</parameter></paramdef>
25
+  <paramdef>void *<parameter>data</parameter></paramdef>
26
+  <paramdef>int <parameter>data_len</parameter></paramdef>
27
+  <paramdef>int <parameter>auto_free</parameter></paramdef>
28
+</funcprototype>
29
+
30
+</funcsynopsis></refsynopsisdiv>
31
+
32
+<refsect1><title>Description</title>
33
+<para>Initializes message structure with given data and given data length. If
34
+<parameter>auto_free</parameter> is set, the message can be be freed
35
+using <function>free_message</function> and such unremoved messages are freed
36
+automaticaly with <function>msg_queue_destroy</function>. If this flag is not set,
37
+calling <function>free message</function> will not do anything and the message
38
+and message data must be freed explicitly by caller.
39
+<!-- detailed description -->
40
+</para>
41
+
42
+</refsect1>
43
+
44
+<refsect1><title>See Also</title>
45
+<para>
46
+<!-- references to other pages -->
47
+<xref linkend="create_message"/>, <xref linkend="create_message_ex"/>, <xref
48
+linkend="free_message"/>
49
+</para>
50
+</refsect1>
51
+
52
+</refentry> 
53
+
0 54
new file mode 100644
... ...
@@ -0,0 +1,55 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="init_output_sstream"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>init_output_sstream</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>init_output_sstream</refname> <!-- function name -->
14
+<refpurpose>initializes serialization stream for output</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/serialize.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>int <function>init_output_sstream</function></funcdef>
24
+  <paramdef>sstream_t *<parameter>ss</parameter></paramdef>
25
+  <paramdef>int <parameter>out_buff_resize</parameter></paramdef>
26
+</funcprototype>
27
+
28
+</funcsynopsis></refsynopsisdiv>
29
+
30
+<refsect1><title>Description</title>
31
+<para>Initializes given serialization stream for output. Parameter
32
+<parameter>out_buff_resize</parameter> is stored into
33
+<structname>sstream_t</structname> structure and specifies the size of newly
34
+allocated data buffers. Data buffers are allocated when needed during output.
35
+<!-- detailed description -->
36
+</para>
37
+
38
+</refsect1>
39
+
40
+<refsect1><title>Return value</title>
41
+<para>
42
+Returns 0 on success, non-zero on error.
43
+<!-- return value description -->
44
+</para>
45
+</refsect1>
46
+
47
+<refsect1><title>See Also</title>
48
+<para>
49
+<!-- references to other pages -->
50
+<xref linkend="sstream_t"/>, <xref linkend="dstring_t"/>
51
+</para>
52
+</refsect1>
53
+
54
+</refentry> 
55
+
0 56
new file mode 100644
... ...
@@ -0,0 +1,50 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="is_msg_queue_empty"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>is_msg_queue_empty</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>is_msg_queue_empty</refname> <!-- function name -->
14
+<refpurpose>test if message queue empty</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/msg_queue.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>int <function>is_msg_queue_empty</function></funcdef>
24
+  <paramdef>msg_queue_t *<parameter>q</parameter></paramdef>
25
+</funcprototype>
26
+
27
+</funcsynopsis></refsynopsisdiv>
28
+
29
+<refsect1><title>Description</title>
30
+<para>Tests message queue if it is empty.
31
+<!-- detailed description -->
32
+</para>
33
+
34
+</refsect1>
35
+
36
+<refsect1><title>Return value</title>
37
+<para>Returns nonzero if message queue empty, zero otherwise.
38
+<!-- return value description -->
39
+</para>
40
+</refsect1>
41
+
42
+<refsect1><title>See Also</title>
43
+<para>
44
+<xref linkend="push_message"/>, <xref linkend="pop_message"/>
45
+<!-- references to other pages -->
46
+</para>
47
+</refsect1>
48
+
49
+</refentry> 
50
+
0 51
new file mode 100644
... ...
@@ -0,0 +1,29 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<reference id="memory">
7
+<title>Memory operations</title>
8
+
9
+<partintro>
10
+<para>Memory operations are common for whole CDS library. Because it must work
11
+together with SER's memory management and must work without it too, there are
12
+standalone functions (?macros in the future?) which cover internal
13
+implementation of memory allocation/deallocation functions.
14
+</para>
15
+
16
+<para>It is possible to redefine these functions to help with memory debugging
17
+or for monitoring purposes or so.
18
+</para>
19
+
20
+<!--
21
+<para>It might be useful some parts of code determined for SER probe out of it,
22
+with a memory debugging tool like valgrind
23
+</para> -->
24
+</partintro>
25
+
26
+<include xmlns="http://www.w3.org/2001/XInclude" href="cds_malloc.xml"/>
27
+<include xmlns="http://www.w3.org/2001/XInclude" href="cds_free.xml"/>
28
+
29
+</reference>
0 30
new file mode 100644
... ...
@@ -0,0 +1,76 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="mq_message_t">
7
+
8
+<refmeta><refentrytitle>mq_message_t</refentrytitle>
9
+<manvolnum>3</manvolnum></refmeta>
10
+
11
+<refnamediv><refname>mq_message_t</refname>
12
+<refpurpose>message data structure</refpurpose>
13
+</refnamediv>
14
+
15
+<refsynopsisdiv><synopsis>
16
+#include &lt;cds/msg_queue.h&gt;
17
+
18
+typedef struct _mq_message_t {
19
+	void *data;
20
+	int data_len;
21
+	struct _mq_message_t *next;
22
+	enum { 
23
+		message_allocated_with_data, 
24
+		message_holding_data_ptr 
25
+	} allocation_style;
26
+	char data_buf[1];
27
+} mq_message_t;
28
+</synopsis></refsynopsisdiv>
29
+
30
+<refsect1><title>Description</title>
31
+
32
+<para>Data structure used as basic element in message queue. Pointer to
33
+message data should be obtained by <function>get_message_data</function>.
34
+</para>
35
+
36
+<para>There are more possibilities how to allocate message data:
37
+<itemizedlist>
38
+	<listitem><para>explicitly, data buffer is allocated outside of
39
+	<structname>mq_message_t</structname> structure and only pointer to it is stored
40
+	in this structure, see <xref linkend="create_message"/>
41
+	<!-- - in this case the data must be deallocated explicitly--></para></listitem>
42
+	
43
+	<listitem><para>implicitly, data buffer is allocated together with
44
+	<structname>mq_message_t</structname> structure - data must be copied into
45
+	it after structure allocation, see <xref linkend="create_message_ex"/></para></listitem>
46
+
47
+	<listitem><para>there is third possibility, that data and message - both -
48
+	are allocated/freed by caller without using
49
+	<function>create_message</function>, <function>create_message_ex</function> and 
50
+	<function>msg_free</function>, see <xref linkend="init_message_ex"/></para>
51
+<!--	<para>In this case might be the <structname>mq_message_t</structname> for
52
+	example a part of the data structure.</para>
53
+	<para>This is not recomended because of
54
+	future possibility of <quote>network message queues</quote> and the
55
+	framework between could not free message memory.</para>-->
56
+	</listitem>
57
+</itemizedlist>
58
+</para>
59
+
60
+<para>More different data allocation methods are due to more efficiency - less
61
+memory allocation calls and less fragmentation in second case, but more common
62
+and may be simpler for usage in first case.
63
+</para>
64
+
65
+<para>Warning: internal implementation of this structure may change, use it only
66
+through existing functions.
67
+</para>
68
+</refsect1>
69
+
70
+<refsect1><title>See Also</title>
71
+<para><xref linkend="msg_queue_t"/>
72
+</para>
73
+</refsect1>
74
+
75
+</refentry> 
76
+
0 77
new file mode 100644
... ...
@@ -0,0 +1,35 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<reference id="msg_queue">
7
+<title>Message queue</title>
8
+
9
+<partintro>
10
+<para>Message queue is implementation of simple FIFO. It is declared in
11
+<filename>msg_queue.h</filename>.
12
+</para>
13
+
14
+<!--
15
+<para> TODO: describe element allocation methods !
16
+</para> -->
17
+</partintro>
18
+
19
+<include xmlns="http://www.w3.org/2001/XInclude" href="msg_queue_t.xml"/>
20
+<include xmlns="http://www.w3.org/2001/XInclude" href="mq_message_t.xml"/>
21
+
22
+<include xmlns="http://www.w3.org/2001/XInclude" href="msg_queue_init.xml"/>
23
+<include xmlns="http://www.w3.org/2001/XInclude" href="msg_queue_init_ex.xml"/>
24
+<include xmlns="http://www.w3.org/2001/XInclude" href="msg_queue_destroy.xml"/>
25
+
26
+<include xmlns="http://www.w3.org/2001/XInclude" href="push_message.xml"/>
27
+<include xmlns="http://www.w3.org/2001/XInclude" href="pop_message.xml"/>
28
+<include xmlns="http://www.w3.org/2001/XInclude" href="is_msg_queue_empty.xml"/>
29
+
30
+<include xmlns="http://www.w3.org/2001/XInclude" href="create_message.xml"/>
31
+<include xmlns="http://www.w3.org/2001/XInclude" href="create_message_ex.xml"/>
32
+<include xmlns="http://www.w3.org/2001/XInclude" href="init_message_ex.xml"/>
33
+<include xmlns="http://www.w3.org/2001/XInclude" href="free_message.xml"/>
34
+
35
+</reference>
0 36
new file mode 100644
... ...
@@ -0,0 +1,55 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="msg_queue_destroy"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>msg_queue_destroy</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>msg_queue_destroy</refname> <!-- function name -->
14
+<refpurpose>destroy message queue</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/msg_queue.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>void <function>msg_queue_destroy</function></funcdef>
24
+  <paramdef>msg_queue_t *<parameter>q</parameter></paramdef>
25
+</funcprototype>
26
+
27
+</funcsynopsis></refsynopsisdiv>
28
+
29
+<refsect1><title>Description</title>
30
+<para>Destroys initialized message queue. After calling
31
+<function>msg_queue_destroy</function> can not be called any of message queue
32
+manipulation functions except <function>msg_queue_init</function>.
33
+<!-- detailed description -->
34
+</para>
35
+
36
+<para>All messages which stay in the queue and have <parameter>auto_free</parameter> flag set 
37
+are automaticaly freed using <function>free_message</function>. 
38
+It depends on allocation manner of messages if it is sufficient.
39
+</para>
40
+
41
+</refsect1>
42
+
43
+<refsect1><title>See Also</title>
44
+<para>
45
+<xref linkend="msg_queue_init"/>, <xref linkend="msg_queue_init_ex"/>, <xref
46
+linkend="msg_queue_t"/>, <xref linkend="mq_message_t"/>, <xref
47
+linkend="free_message"/>, <xref linkend="init_message_ex"/>
48
+<!--, <xref
49
+linkend="free_message"/>-->
50
+<!-- references to other pages -->
51
+</para>
52
+</refsect1>
53
+
54
+</refentry> 
55
+
0 56
new file mode 100644
... ...
@@ -0,0 +1,51 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="msg_queue_init"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>msg_queue_init</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>msg_queue_init</refname> <!-- function name -->
14
+<refpurpose>message queue initialization</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/msg_queue.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>int <function>msg_queue_init</function></funcdef>
24
+  <paramdef>msg_queue_t *<parameter>q</parameter></paramdef>
25
+</funcprototype>
26
+
27
+</funcsynopsis></refsynopsisdiv>
28
+
29
+<refsect1><title>Description</title>
30
+<para>Initializes synchronized (using internal mutex) message queue structure.
31
+<!-- detailed description -->
32
+</para>
33
+
34
+</refsect1>
35
+
36
+<refsect1><title>Return value</title>
37
+<para>
38
+<!-- return value description -->
39
+Returns 0 on success, non-zero on error.
40
+</para>
41
+</refsect1>
42
+
43
+<refsect1><title>See Also</title>
44
+<para>
45
+<xref linkend="msg_queue_init_ex"/>, <xref linkend="msg_queue_destroy"/>
46
+<!-- references to other pages -->
47
+</para>
48
+</refsect1>
49
+
50
+</refentry> 
51
+
0 52
new file mode 100644
... ...
@@ -0,0 +1,55 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="msg_queue_init_ex"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>msg_queue_init_ex</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>msg_queue_init_ex</refname> <!-- function name -->
14
+<refpurpose>message queue initialization</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/msg_queue.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>int <function>msg_queue_init_ex</function></funcdef>
24
+  <paramdef>msg_queue_t *<parameter>q</parameter></paramdef>
25
+  <paramdef>int <parameter>synchronized</parameter></paramdef>
26
+</funcprototype>
27
+
28
+</funcsynopsis></refsynopsisdiv>
29
+
30
+<refsect1><title>Description</title>
31
+<para>Initializes message queue structure. The value of
32
+<parameter>synchronized</parameter> may be 0 or 1. Zero means, that the message
33
+queue will not use mutex for internal data access (will be NOT synchronized), 1
34
+means that message queue will be synchronized by mutex created internaly.
35
+<!-- detailed description -->
36
+</para>
37
+
38
+</refsect1>
39
+
40
+<refsect1><title>Return value</title>
41
+<para>
42
+<!-- return value description -->
43
+Returns 0 on success, non-zero on error.
44
+</para>
45
+</refsect1>
46
+
47
+<refsect1><title>See Also</title>
48
+<para>
49
+<xref linkend="msg_queue_init"/>, <xref linkend="msg_queue_destroy"/>
50
+<!-- references to other pages -->
51
+</para>
52
+</refsect1>
53
+
54
+</refentry> 
55
+
0 56
new file mode 100644
... ...
@@ -0,0 +1,43 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="msg_queue_t">
7
+
8
+<refmeta><refentrytitle>msg_queue_t</refentrytitle>
9
+<manvolnum>3</manvolnum></refmeta>
10
+
11
+<refnamediv><refname>msg_queue_t</refname>
12
+<refpurpose>message queue data structure</refpurpose>
13
+</refnamediv>
14
+
15
+<refsynopsisdiv><synopsis>
16
+#include &lt;cds/msg_queue.h&gt;
17
+
18
+typedef struct msg_queue {
19
+	mq_message_t *first;
20
+	mq_message_t *last;
21
+	cds_mutex_t q_mutex;
22
+	int use_mutex;
23
+} msg_queue_t;
24
+
25
+</synopsis></refsynopsisdiv>
26
+
27
+<refsect1><title>Description</title>
28
+<para>Message queue is implemented as simple linked list of elements. Message
29
+queue may be locked or not - it depends on initialization.
30
+</para> 
31
+<para>Warning: internal implementation of this structure may change, use it only
32
+through existing functions.
33
+</para>
34
+</refsect1>
35
+
36
+<refsect1><title>See Also</title>
37
+<para>
38
+<xref linkend="mq_message_t"/>
39
+</para>
40
+</refsect1>
41
+
42
+</refentry> 
43
+
0 44
new file mode 100644
... ...
@@ -0,0 +1,53 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="pop_message"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>pop_message</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>pop_message</refname> <!-- function name -->
14
+<refpurpose>pop message from the queue</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/msg_queue.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>mq_message_t *<function>pop_message</function></funcdef>
24
+  <paramdef>msg_queue_t *<parameter>q</parameter></paramdef>
25
+</funcprototype>
26
+
27
+</funcsynopsis></refsynopsisdiv>
28
+
29
+<refsect1><title>Description</title>
30
+<para>Removes first message from the queue. If the queue is empty or an error
31
+occured it returns NULL value. Removed messages are NOT automaticaly freed -
32
+caller must use <function>free_message</function> or free it itself (see <xref
33
+linkend="free_message"/>)!
34
+</para>
35
+
36
+</refsect1>
37
+
38
+<refsect1><title>Return value</title>
39
+<para>Returns pointer to message removed from the queue. If the queue is empty
40
+or an error occured the return value is NULL.
41
+<!-- return value description -->
42
+</para>
43
+</refsect1>
44
+
45
+<refsect1><title>See Also</title>
46
+<para>
47
+<xref linkend="push_message"/>, <xref linkend="free_message"/>
48
+<!-- references to other pages -->
49
+</para>
50
+</refsect1>
51
+
52
+</refentry> 
53
+
0 54
new file mode 100644
... ...
@@ -0,0 +1,60 @@
1
+<?xml version="1.0" encoding="UTF-8"?>
2
+
3
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
4
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
+
6
+<refentry id="push_message"> <!-- ID for references -->
7
+
8
+<refmeta>
9
+<refentrytitle>push_message</refentrytitle> <!-- title shown in references -->
10
+<manvolnum>3</manvolnum></refmeta> <!-- man volume id (3 for libraries) -->
11
+
12
+<refnamediv>
13
+<refname>push_message</refname> <!-- function name -->
14
+<refpurpose>push message into message queue</refpurpose> <!-- short function description -->
15
+</refnamediv>
16
+
17
+<refsynopsisdiv><funcsynopsis>
18
+<funcsynopsisinfo>
19
+#include &lt;cds/msg_queue.h&gt; <!-- included headers -->
20
+</funcsynopsisinfo>
21
+
22
+<funcprototype> <!-- function prototype -->
23
+  <funcdef>int <function>push_message</function></funcdef>
24
+  <paramdef>msg_queue_t *<parameter>q</parameter></paramdef>
25
+  <paramdef>mq_message_t *<parameter>msg</parameter></paramdef>
26
+</funcprototype>
27
+
28
+</funcsynopsis></refsynopsisdiv>
29
+
30
+<refsect1><title>Description</title>
31
+<para>Function pushes initialized message into message queue. This
32
+message may be removed from the queue using <function>pop_message</function>.
33
+Unremoved messages are automaticaly freed by <function>msg_queue_destroy</function> 
34
+(depending on message initialization, see <xref
35
+linkend="create_message"/>, <xref linkend="create_message_ex"/> and <xref
36
+linkend="init_message_ex"/>).
37
+<!-- detailed description -->
38
+</para>
39
+
40
+</refsect1>
41
+
42
+<refsect1><title>Return value</title>
43
+<para>
44
+<!-- return value description -->
45
+Returns 0 on success, non-zero on error.
46
+</para>
47
+</refsect1>
48
+
49
+<refsect1><title>See Also</title>
50
+<para>
51
+<!-- references to other pages -->
52
+<xref linkend="pop_message"/>, 
53
+<xref linkend="create_message"/>, 
54
+<xref linkend="create_message_ex"/>, 
55
+<xref linkend="init_message_ex"/>
56
+</para>
57
+</refsect1>
58
+
59
+</refentry> 
60
+
... ...
@@ -15,5 +15,22 @@ serialization (see <xref linkend="sstream_t.example"/>).</para>
15 15
 </partintro>
16 16
 
17 17
 <include xmlns="http://www.w3.org/2001/XInclude" href="sstream_t.xml"/>
18
+<include xmlns="http://www.w3.org/2001/XInclude" href="init_input_sstream.xml"/>
19
+<include xmlns="http://www.w3.org/2001/XInclude" href="init_output_sstream.xml"/>
20
+<include xmlns="http://www.w3.org/2001/XInclude" href="get_serialized_sstream.xml"/>
21
+<include xmlns="http://www.w3.org/2001/XInclude" href="destroy_sstream.xml"/>