malloc_test: doc updates & generated README
authorAndrei Pelinescu-Onciul <andrei@iptel.org>
Thu, 11 Mar 2010 20:06:17 +0000 (21:06 +0100)
committerAndrei Pelinescu-Onciul <andrei@iptel.org>
Thu, 11 Mar 2010 20:16:12 +0000 (21:16 +0100)
modules/malloc_test/README [new file with mode: 0644]
modules/malloc_test/doc/malloc_test.xml
modules/malloc_test/doc/params.xml
modules/malloc_test/doc/rpc.xml [new file with mode: 0644]
modules/malloc_test/malloc_test.c

diff --git a/modules/malloc_test/README b/modules/malloc_test/README
new file mode 100644 (file)
index 0000000..a989909
--- /dev/null
@@ -0,0 +1,230 @@
+1. malloc_test Module
+
+Andrei Pelinescu-Onciul
+
+   iptelorg GmbH
+
+   Copyright © 2010 iptelorg GmbH
+   Revision History
+   Revision $Revision$ $Date$
+     __________________________________________________________________
+
+   1.1. Overview
+   1.2. Parameters
+
+        1.2.1. check_content
+
+   1.3. Functions
+
+        1.3.1. mt_mem_alloc(size)
+        1.3.2. mt_mem_free()
+
+   1.4. malloc_test RPC Functions
+
+        1.4.1. mt.mem_alloc size [unit]
+        1.4.2. mt.mem_free [size] [unit]
+        1.4.3. mt.mem_used [unit]
+        1.4.4. mt.mem_rnd_alloc min max total [unit]
+        1.4.5. mt.mem_test_start min max total min_int max_int total_time
+                [unit]
+
+        1.4.6. mt.mem_test_stop id
+        1.4.7. mt.mem_test_destroy id
+        1.4.8. mt.mem_test_destroy_all id
+        1.4.9. mt.mem_test_list [id] [unit]
+
+1.1. Overview
+
+   This is a debugging/test module. It implements functions (both script
+   and rpcs) that can be used to stress the memory allocator or force
+   memory leaks.
+
+Warning
+
+   This module should never be used in a production environment.
+
+1.2. Parameters
+
+   Revision History
+   Revision $Revision$ $Date$
+
+1.2.1. check_content
+
+   When doing the tests, check also for the possibility of the memory
+   being overwritten. When activated, the allocated memory will be filled
+   with a special pattern, that will be checked on free.
+
+   Default: 0 (off).
+
+   It can be changed also at runtime, via the rpc interface.
+
+   Example 1.  Set check_content in the config file
+modparam("malloc_test", "check_content", 1)
+
+   Example 2.  Set check_content at runtime via sercmd
+$ sercmd cfg.set_now_int malloc_test check_content 1
+
+1.3. Functions
+
+   Revision History
+   Revision $Revision$ $Date$
+
+1.3.1. mt_mem_alloc(size)
+
+   Allocates size bytes.
+
+Note
+
+   This is a debugging function for simulating memory leaks or stressing
+   the memory allocator. It should not be used in production setups
+
+   Example 3. men_alloc usage
+...
+mem_alloc(1048576); # 1MB
+...
+
+1.3.2. mt_mem_free()
+
+   Frees all the memory allocated with mem_alloc() up to this point.
+
+Note
+
+   This is a debugging function for simulating memory leaks or stressing
+   the memory allocator. It should not be used in production setups
+
+   Example 4. mem_free usage
+...
+mem_free();
+...
+
+1.4. malloc_test RPC Functions
+
+   Revision History
+   Revision $Revision$ $Date$
+
+1.4.1.  mt.mem_alloc size [unit]
+
+   Allocates the specified number of bytes. unit is optional and can be
+   one of:
+     * b - bytes
+     * k - KB
+     * m - MB
+     * g - GB
+
+   Example 5. mt.mem_alloc usage
+ $ sercmd mt.mem_alloc 10 k
+
+1.4.2.  mt.mem_free [size] [unit]
+
+   Frees at least size bytes from the memory allocated by other
+   malloc_test functions (e.g. mt.mem_alloc).
+
+   size is optional. If missing, everything will be freed.
+
+   unit is optional and can be one of:
+     * b - bytes
+     * k - KB
+     * m - MB
+     * g - GB
+
+   Example 6. mt.mem_free usage
+ $ sercmd mt.mem_free 1 m
+
+1.4.3.  mt.mem_used [unit]
+
+   Returns/displays how many bytes are allocated. The default unit is
+   bytes (for all the possible units see above).
+
+   unit is optional and can be one of:
+     * b - bytes
+     * k - KB
+     * m - MB
+     * g - GB
+
+   Example 7. mt.mem_used usage
+ $ sercmd mt.mem_used
+9221460
+
+1.4.4. mt.mem_rnd_alloc min max total [unit]
+
+   Allocates total_size memory, in pieces of random size between min ..
+   max (inclusive). unit is optional and represents the unit for all the
+   given sizes (see above).
+
+   Example 8. mt.mem_rnd_alloc usage
+ $ sercmd mt.mem_rnd_alloc 1 64 10240 k
+
+1.4.5.  mt.mem_test_start min max total min_int max_int total_time [unit]
+
+   Starts a malloc test that will take total_time to execute. Memory
+   allocations will be performed at intervals randomly chosen between
+   min_int and max_int (in ms). Each allocation will have a randomly
+   chosen size between min and max unit bytes. After total unit bytes are
+   allocated, everything is released/freed again and the allocations are
+   restarted. All the times are expressed in milliseconds. unit is
+   optional and represents the unit for all the given sizes (see above).
+
+   Several tests can be run in parallel.
+
+   Returns the test id.
+
+   Example 9. mt.mem_test_start usage
+ $ sercmd mt.mem_test_start 15 64 25000 128 1500 3600000 k
+1
+
+1.4.6.  mt.mem_test_stop id
+
+   Stops the test indentified by id.
+
+   Example 10. mt.mem_test_stop usage
+ $ sercmd mt.mem_test_stop 1
+
+1.4.7.  mt.mem_test_destroy id
+
+   Destroys the test indentified by id (besides stopping it, it also frees
+   all the data, including the statistics).
+
+   Example 11. mt.mem_test_destroy usage
+ $ sercmd mt.mem_test_destroy 1
+
+1.4.8.  mt.mem_test_destroy_all id
+
+   Destroys all the running or stopped tests.
+
+   Example 12. mt.mem_test_destroy_all usage
+ $ sercmd mt.mem_test_destroy_all
+
+1.4.9.  mt.mem_test_list [id] [unit]
+
+   Returns/displays data about the test identified by id, or if no id is
+   specified, it lists all the tests (running or stopped).
+
+   unit is optional. The default is is bytes (for all the possible units
+   see above).
+
+   Example 13. mt.mem_test_list usage
+ $ sercmd mt.mem_test_list
+{
+        ID           : 2
+        run time (s) : 1471
+        remaining (s): 2128
+        allocations  : 1749
+        errors       : 24
+        overflows    : 2
+        total alloc  : 69614530
+        min          : 15360
+        max          : 65536
+        total        : 25600000
+}
+{
+        ID           : 1
+        run time (s) : 3600
+        remaining (s): 0
+        allocations  : 4268
+        errors       : 640
+        overflows    : 4
+        total alloc  : 144220713
+        min          : 15360
+        max          : 65536
+        total        : 29696000
+}
index e53fe56..13c9856 100644 (file)
@@ -2,7 +2,11 @@
 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
        [ <!ENTITY % local.common.attrib
-        "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">]
+        "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">
+        <!-- Include general documentation entities -->
+        <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+        %docentities;
+       ]
 >
 
 <section id="malloc_test" xmlns:xi="http://www.w3.org/2001/XInclude">
@@ -44,4 +48,5 @@
        </section>
        <xi:include href="params.xml"/>
        <xi:include href="functions.xml"/>
+       <xi:include href="rpc.xml"/>
 </section>
index 3fe8396..8e894bf 100644 (file)
@@ -1,6 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
-   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+       "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+       [ <!-- Include general documentation entities -->
+               <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+               %docentities;
+       ]
+>
 
 <section id="malloc_test.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
        <sectioninfo>
@@ -40,7 +45,7 @@ modparam("malloc_test", "check_content", 1)
                                Set <varname>check_content</varname> at runtime via sercmd
                        </title>
                        <programlisting>
-$ sercmd cfg.set_now_int malloc_test check_content 1
+$ &sercmd; cfg.set_now_int malloc_test check_content 1
                        </programlisting>
                </example>
        </section>
diff --git a/modules/malloc_test/doc/rpc.xml b/modules/malloc_test/doc/rpc.xml
new file mode 100644 (file)
index 0000000..667450a
--- /dev/null
@@ -0,0 +1,229 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
+       "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+       [ <!-- Include general documentation entities -->
+               <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+               %docentities;
+       ]
+>
+
+<section id="malloc_test.rpcs" xmlns:xi="http://www.w3.org/2001/XInclude">
+       <sectioninfo>
+               <revhistory>
+                       <revision>
+                               <revnumber>$Revision$</revnumber>
+                               <date>$Date$</date>
+                       </revision>
+               </revhistory>
+       </sectioninfo>
+       <title>malloc_test RPC Functions</title>
+
+       <section id="mt.mem_alloc">
+               <title> <function>mt.mem_alloc size [unit]</function></title>
+               <para>
+                       Allocates the specified number of bytes.
+                       <varname>unit</varname> is optional and can be one of:
+                       <itemizedlist>
+                       <listitem><para><emphasis>b</emphasis> - bytes </para></listitem>
+                       <listitem><para><emphasis>k</emphasis> - KB </para></listitem>
+                       <listitem><para><emphasis>m</emphasis> - MB </para></listitem>
+                       <listitem><para><emphasis>g</emphasis> - GB </para></listitem>
+                       </itemizedlist>
+               </para>
+               <example>
+                       <title><function>mt.mem_alloc</function> usage</title>
+                       <programlisting>
+ $ &sercmd; mt.mem_alloc 10 k
+                       </programlisting>
+               </example>
+       </section>
+
+       <section id="mt.mem_free">
+               <title> <function>mt.mem_free [size] [unit]</function></title>
+               <para>
+                       Frees at least <varname>size</varname> bytes from the memory
+                       allocated by other malloc_test functions (e.g. mt.mem_alloc).
+               </para>
+               <para>
+                       <varname>size</varname> is optional. If missing, everything will
+                       be freed.
+               </para>
+               <para>
+                       <varname>unit</varname> is optional and can be one of:
+                       <itemizedlist>
+                       <listitem><para><emphasis>b</emphasis> - bytes </para></listitem>
+                       <listitem><para><emphasis>k</emphasis> - KB </para></listitem>
+                       <listitem><para><emphasis>m</emphasis> - MB </para></listitem>
+                       <listitem><para><emphasis>g</emphasis> - GB </para></listitem>
+                       </itemizedlist>
+               </para>
+               <example>
+                       <title><function>mt.mem_free</function> usage</title>
+               <programlisting>
+ $ &sercmd; mt.mem_free 1 m
+               </programlisting>
+               </example>
+       </section>
+
+       <section id="mt.mem_used">
+               <title> <function>mt.mem_used [unit]</function></title>
+               <para>
+                       Returns/displays how many bytes are allocated. The default
+                       unit is bytes (for all the possible units see above).
+               </para>
+               <para>
+                       <varname>unit</varname> is optional and can be one of:
+                       <itemizedlist>
+                       <listitem><para><emphasis>b</emphasis> - bytes </para></listitem>
+                       <listitem><para><emphasis>k</emphasis> - KB </para></listitem>
+                       <listitem><para><emphasis>m</emphasis> - MB </para></listitem>
+                       <listitem><para><emphasis>g</emphasis> - GB </para></listitem>
+                       </itemizedlist>
+               </para>
+               <example>
+                       <title><function>mt.mem_used</function> usage</title>
+               <programlisting>
+ $ &sercmd; mt.mem_used
+9221460
+               </programlisting>
+               </example>
+       </section>
+
+       <section id="mt.mem_rnd_alloc">
+               <title><function>mt.mem_rnd_alloc min max total [unit]</function>
+               </title>
+               <para>
+                       Allocates <varname>total_size</varname> memory, in pieces of
+                       random size between
+                       <varname>min</varname> .. <varname>max</varname> (inclusive).
+                       <varname>unit</varname> is optional and represents the unit for
+                       all the given sizes (see above).
+               </para>
+               <example>
+                       <title><function>mt.mem_rnd_alloc</function> usage</title>
+                       <programlisting>
+ $ &sercmd; mt.mem_rnd_alloc 1 64 10240 k
+                       </programlisting>
+               </example>
+       </section>
+
+       <section id="mt.mem_test_start">
+               <title>
+                       <function>
+                               mt.mem_test_start min max total min_int max_int total_time
+                               [unit]
+                       </function>
+               </title>
+               <para>
+                       Starts a malloc test that will take <varname>total_time</varname>
+                       to execute. Memory allocations will be performed at intervals
+                       randomly chosen between <varname>min_int</varname> and
+                       <varname>max_int</varname> (in ms). Each allocation will have a
+                       randomly chosen size between <varname>min</varname> and
+                       <varname>max</varname> <varname>unit</varname> bytes. After
+                       <varname>total</varname> <varname>unit</varname> bytes are
+                       allocated, everything is released/freed again and the allocations
+                       are restarted. All the times are expressed in milliseconds.
+                       <varname>unit</varname> is optional and represents the unit for
+                       all the given sizes (see above).
+               </para>
+               <para>
+                       Several tests can be run in parallel.
+               </para>
+               <para>
+                       Returns the test id.
+               </para>
+               <example>
+                       <title><function>mt.mem_test_start</function> usage</title>
+                       <programlisting>
+ $ &sercmd; mt.mem_test_start 15 64 25000 128 1500 3600000 k
+1
+                       </programlisting>
+               </example>
+       </section>
+
+       <section id="mt.mem_test_stop">
+               <title> <function>mt.mem_test_stop id</function></title>
+               <para>
+                       Stops the test indentified by <varname>id</varname>.
+               </para>
+               <example>
+                       <title><function>mt.mem_test_stop</function> usage</title>
+               <programlisting>
+ $ &sercmd; mt.mem_test_stop 1
+               </programlisting>
+               </example>
+       </section>
+
+       <section id="mt.mem_test_destroy">
+               <title> <function>mt.mem_test_destroy id</function></title>
+               <para>
+                       Destroys the test indentified by <varname>id</varname>
+                       (besides stopping it, it also frees all the data, including the
+                       statistics).
+               </para>
+               <example>
+                       <title><function>mt.mem_test_destroy</function> usage</title>
+               <programlisting>
+ $ &sercmd; mt.mem_test_destroy 1
+               </programlisting>
+               </example>
+       </section>
+
+       <section id="mt.mem_test_destroy_all">
+               <title> <function>mt.mem_test_destroy_all id</function></title>
+               <para>
+                       Destroys all the running or stopped tests.
+               </para>
+               <example>
+                       <title><function>mt.mem_test_destroy_all</function> usage</title>
+               <programlisting>
+ $ &sercmd; mt.mem_test_destroy_all
+               </programlisting>
+               </example>
+       </section>
+
+       <section id="mt.mem_test_list">
+               <title> <function>mt.mem_test_list [id] [unit]</function></title>
+               <para>
+                       Returns/displays data about the test identified by
+                       <varname>id</varname>, or if no <varname>id</varname> is
+                       specified, it lists all the tests (running or stopped).
+               </para>
+               <para>
+                       <varname>unit</varname> is optional. The default is
+                       is bytes (for all the possible units see above).
+               </para>
+               <example>
+                       <title><function>mt.mem_test_list</function> usage</title>
+               <programlisting>
+ $ &sercmd; mt.mem_test_list
+{
+       ID           : 2
+       run time (s) : 1471
+       remaining (s): 2128
+       allocations  : 1749
+       errors       : 24
+       overflows    : 2
+       total alloc  : 69614530
+       min          : 15360
+       max          : 65536
+       total        : 25600000
+}
+{
+       ID           : 1
+       run time (s) : 3600
+       remaining (s): 0
+       allocations  : 4268
+       errors       : 640
+       overflows    : 4
+       total alloc  : 144220713
+       min          : 15360
+       max          : 65536
+       total        : 29696000
+}
+               </programlisting>
+               </example>
+       </section>
+
+</section>
index 6cca8c8..89172f1 100644 (file)
@@ -424,7 +424,7 @@ static ticks_t tst_timer(ticks_t ticks, struct timer_ln* tl, void* data)
  *    a random number of bytes, between min & max.
  *  - if total_size is reached, free everything.
  *
- * @returns 0 on success, -1 on error.
+ * @returns test id (>=0) on success, -1 on error.
  */
 static int mem_leak_time_test(unsigned long min, unsigned long max,
                                                                unsigned long total_size,
@@ -434,12 +434,13 @@ static int mem_leak_time_test(unsigned long min, unsigned long max,
        struct rnd_time_test* tst;
        struct rnd_time_test* l;
        ticks_t first_int;
+       int id;
        
        tst = shm_malloc(sizeof(*tst));
        if (tst == 0)
                goto error;
        memset(tst, 0, sizeof(*tst));
-       tst->id = atomic_add_int(&rndt_lst->last_id, 1);
+       id = tst->id = atomic_add_int(&rndt_lst->last_id, 1);
        tst->min = min;
        tst->max = max;
        tst-> total = total_size;
@@ -455,7 +456,7 @@ static int mem_leak_time_test(unsigned long min, unsigned long max,
        lock_release(&rndt_lst->lock);
        if (timer_add(&tst->timer, MIN_unsigned(first_int, test_time)) < 0 )
                goto error;
-       return 0;
+       return id;
 error:
        if (tst) {
                lock_get(&rndt_lst->lock);
@@ -735,6 +736,7 @@ static void rpc_mt_test_start(rpc_t* rpc, void* c)
        int min, max, total_size;
        int min_intvrl, max_intvrl, total_time;
        int rs;
+       int id;
        
        if (rpc->scan(c, "dddddd", &min, &max, &total_size,
                                                                &min_intvrl, &max_intvrl, &total_time) < 6) {
@@ -752,14 +754,16 @@ static void rpc_mt_test_start(rpc_t* rpc, void* c)
                rpc->fault(c, 400, "invalid time intervals values");
                return;
        }
-       if (mem_leak_time_test((unsigned long)min << rs,
+       if ((id=mem_leak_time_test((unsigned long)min << rs,
                                         (unsigned long)max << rs,
                                         (unsigned long)total_size <<rs,
                                         MS_TO_TICKS(min_intvrl),
                                         MS_TO_TICKS(max_intvrl),
                                         MS_TO_TICKS(total_time)
-                                        ) < 0) {
+                                        )) < 0) {
                rpc->fault(c, 400, "memory allocation failed");
+       } else {
+               rpc->add(c, "d", id);
        }
        return;
 }
@@ -821,7 +825,8 @@ static void rpc_mt_test_destroy_all(rpc_t* rpc, void* c)
 
 static const char* rpc_mt_test_list_doc[2] = {
        "If a test id parameter is provided it will list the corresponding test,"
-       " else it will list all of them",
+       " else it will list all of them. Use b |k | m | g as a second parameter"
+       " for the size units (default bytes)",
        0
 };