The misctest Module

Andrei Pelinescu-Onciul

   iptelorg GmbH

   Copyright © 2010 iptelorg GmbH
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Parameters

              2.1. memory (int)
              2.2. mem_check_content (int)
              2.3. message (int)
              2.4. message_data (str)
              2.5. message_file (str)
              2.6. lock_threads_mode (int)

        3. Functions

              3.1. mt_mem_alloc(size)
              3.2. mt_mem_free()
              3.3. mt_tcp_thread_exec(text)
              3.4. mt_lock_test(count)
              3.5. mt_lock_threads(nrthreads)
              3.6. mt_unlock_threads(nrops)

        4. RPC Commands

              4.1. mt.mem_alloc size [unit]
              4.2. mt.mem_free [size] [unit]
              4.3. mt.mem_used [unit]
              4.4. mt.mem_rnd_alloc min max total [unit]
              4.5. mt.mem_test_start min max total min_int max_int
                      total_time [unit]

              4.6. mt.mem_test_stop id
              4.7. mt.mem_test_destroy id
              4.8. mt.mem_test_destroy_all id
              4.9. mt.mem_test_list [id] [unit]
              4.10. mt.lock_test [executions]

   List of Examples

   1.1. Set memory in the config file
   1.2. Set mem_check_content in the config file
   1.3. Set mem_check_content at runtime via kamctl
   1.4. Set message in the config file
   1.5. Set message_data in the config file
   1.6. Set message_file in the config file
   1.7. Set lock_threads_mode in the config file
   1.8. men_alloc usage
   1.9. mem_free usage
   1.10. mt_tcp_thread_exec usage
   1.11. mt_lock_test usage
   1.12. mt_lock_threads usage
   1.13. mt_lock_threads usage
   1.14. mt.mem_alloc usage
   1.15. mt.mem_free usage
   1.16. mt.mem_used usage
   1.17. mt.mem_rnd_alloc usage
   1.18. mt.mem_test_start usage
   1.19. mt.mem_test_stop usage
   1.20. mt.mem_test_destroy usage
   1.21. mt.mem_test_destroy_all usage
   1.22. mt.mem_test_list usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Parameters

        2.1. memory (int)
        2.2. mem_check_content (int)
        2.3. message (int)
        2.4. message_data (str)
        2.5. message_file (str)
        2.6. lock_threads_mode (int)

   3. Functions

        3.1. mt_mem_alloc(size)
        3.2. mt_mem_free()
        3.3. mt_tcp_thread_exec(text)
        3.4. mt_lock_test(count)
        3.5. mt_lock_threads(nrthreads)
        3.6. mt_unlock_threads(nrops)

   4. RPC Commands

        4.1. mt.mem_alloc size [unit]
        4.2. mt.mem_free [size] [unit]
        4.3. mt.mem_used [unit]
        4.4. mt.mem_rnd_alloc min max total [unit]
        4.5. mt.mem_test_start min max total min_int max_int total_time
                [unit]

        4.6. mt.mem_test_stop id
        4.7. mt.mem_test_destroy id
        4.8. mt.mem_test_destroy_all id
        4.9. mt.mem_test_list [id] [unit]
        4.10. mt.lock_test [executions]

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.

2. Parameters

   2.1. memory (int)
   2.2. mem_check_content (int)
   2.3. message (int)
   2.4. message_data (str)
   2.5. message_file (str)
   2.6. lock_threads_mode (int)

2.1. memory (int)

   Initialize for memory testing. Set it to 1 to prepare the memory
   testing.

   Default: 0 (off).

   Example 1.1.  Set memory in the config file
...
modparam("misctest", "memory", 1)
...

2.2. mem_check_content (int)

   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.2.  Set mem_check_content in the config file
...
modparam("misctest", "mem_check_content", 1)
...

   Example 1.3.  Set mem_check_content at runtime via kamctl
...
$ kamctl rpc cfg.seti misctest mem_check_content 1
...

2.3. message (int)

   Initialize and perform message testing.

   Default: 0 (off).

   Example 1.4.  Set message in the config file
...
modparam("misctest", "message", 1)
...

2.4. message_data (str)

   Set SIP message data for testing.

   Default: NULL (not set).

   Example 1.5.  Set message_data in the config file
...
modparam("misctest", "message_data", "...")
...

2.5. message_file (str)

   Set path to file from where to read SIP message data for testing.

   Default: NULL (not set).

   Example 1.6.  Set message_file in the config file
...
modparam("misctest", "message_file", "/tmp/sip-data.txt")
...

2.6. lock_threads_mode (int)

   Initialize (1) or not (0) the internal lock for pthreads testing.

   Default: 0 (no initialization).

   Example 1.7.  Set lock_threads_mode in the config file
...
modparam("misctest", "lock_threads_mode", 1)
...

3. Functions

   3.1. mt_mem_alloc(size)
   3.2. mt_mem_free()
   3.3. mt_tcp_thread_exec(text)
   3.4. mt_lock_test(count)
   3.5. mt_lock_threads(nrthreads)
   3.6. mt_unlock_threads(nrops)

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 1.8. men_alloc usage
...
mem_alloc(1048576); # 1MB
...

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 1.9. mem_free usage
...
mem_free();
...

3.3. mt_tcp_thread_exec(text)

   Print the text via the tcp main process threads.

Note

   This is a debugging function for simulating execution on tcp main
   process threads. It should not be used in production setups

   Example 1.10. mt_tcp_thread_exec usage
...
mt_tcp_thread_exec("request $rm uri $ru");
...

3.4.  mt_lock_test(count)

   Lock and unlock the global lock count times.

Note

   This is a debugging function for simulating locking and unlocking of
   global lock. It should not be used in production setups

   Example 1.11.  mt_lock_test usage
...
mt_lock_test(100000000);
...

3.5.  mt_lock_threads(nrthreads)

   Creates a set of threads that try to use the internal lock (see also
   lock_threads_mode parameter).

Note

   This is a debugging function to do locking and unlocking of an internal
   global lock from threads. It should not be used in production setups.

   Example 1.12.  mt_lock_threads usage
...
mt_lock_threads("4");
...

3.6.  mt_unlock_threads(nrops)

   Unlock the internal global lock used by mt_lock_threads(). It is done
   nrops-times.

Note

   This is a debugging function to do locking and unlocking of an internal
   global lock from threads. It should not be used in production setups.

   Example 1.13.  mt_lock_threads usage
...
mt_unlock_threads("4");
...

4. RPC Commands

   4.1. mt.mem_alloc size [unit]
   4.2. mt.mem_free [size] [unit]
   4.3. mt.mem_used [unit]
   4.4. mt.mem_rnd_alloc min max total [unit]
   4.5. mt.mem_test_start min max total min_int max_int total_time [unit]
   4.6. mt.mem_test_stop id
   4.7. mt.mem_test_destroy id
   4.8. mt.mem_test_destroy_all id
   4.9. mt.mem_test_list [id] [unit]
   4.10. mt.lock_test [executions]

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 1.14.  mt.mem_alloc usage
 $ kamctl rpc mt.mem_alloc 10 k

4.2.  mt.mem_free [size] [unit]

   Frees at least size bytes from the memory allocated by other misctest
   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 1.15.  mt.mem_free usage
 $ kamctl rpc mt.mem_free 1 m

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 1.16.  mt.mem_used usage
 $ kamctl rpc mt.mem_used
9221460

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 1.17.  mt.mem_rnd_alloc usage
 $ kamctl rpc mt.mem_rnd_alloc 1 64 10240 k

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 1.18.  mt.mem_test_start usage
 $ kamctl rpc mt.mem_test_start 15 64 25000 128 1500 3600000 k
1

4.6.  mt.mem_test_stop id

   Stops the test identified by id.

   Example 1.19.  mt.mem_test_stop usage
 $ kamctl rpc mt.mem_test_stop 1

4.7.  mt.mem_test_destroy id

   Destroys the test identified by id (besides stopping it, it also frees
   all the data, including the statistics).

   Example 1.20.  mt.mem_test_destroy usage
 $ kamcmd mt.mem_test_destroy 1

4.8.  mt.mem_test_destroy_all id

   Destroys all the running or stopped tests.

   Example 1.21.  mt.mem_test_destroy_all usage
 $ kamcmd mt.mem_test_destroy_all

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 1.22.  mt.mem_test_list usage
 $ kamcmd 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
}

4.10.  mt.lock_test [executions]

   The mt.lock_test RPC command performs a lock/unlock stress test using a
   global lock. It is primarily intended for debugging and performance
   testing of the locking subsystem.

   Usage:
        kamctl rpc mt.lock_test [executions]

     * executions (integer): Number of times to lock and unlock.

   If the argument is provided, it must be a positive integer. If if the
   argument is not a positive integer, the command will return an error.

   Example:
        kamctl rpc mt.lock_test 10000

   This will perform 10,000 lock/unlock operations.
