Next: Generating Random Numbers, Up: Random Number Generators [Contents][Index]

A random number generator is referred to by a handle.

- Data type:
**qsmm_rng_t** This is a type for a handle of random number generator. It is a pointer, so variables of this type can have the

`NULL`

value. The functions`qsmm_rng_create`

and`qsmm_rng_create_custom`

allocate a new handle. The function`qsmm_rng_destroy`

frees an existing handle.After allocating a handle, it can be passed to API functions that take an argument of type

`qsmm_rng_t`

until the handle is freed. An allocated handle can also be set as the value of field`rng`

of structures that specify parameters of creating an actor or a multinode model. A lifetime of the allocated handle should be longer than a lifetime of the actor or the multinode model.

The function `qsmm_get_actor_rng`

returns a handle of random number generator specified in the field `rng`

of structure `qsmm_actor_desc_s`

when creating the actor, or the handle of an instance of default random number generator allocated automatically if 0 is specified in that field.
The function `qsmm_get_rng`

returns a handle of random number generator specified in the field `rng`

of structure `qsmm_desc_s`

when creating the multinode model, or the handle of an instance of default random number generator allocated automatically if 0 is specified in that field.

To create a random number generator, which is an instance of default random number generator, the following function can be used.

- Function:
*int***qsmm_rng_create***(qsmm_rng_t **`rng_p`) This function creates a random number generator and stores its newly allocated handle in *

`rng_p`. The function creates either a random number generator, which type is defined by a user-supplied function`qsmm_proxy_func_t`

and its parameter set by a call to`qsmm_set_rng_default`

(see Custom Random Number Generators, for more information), or a random number generator of a standard type (defined when configuring the package) if the user-supplied function is not set.The function returns a non-negative value on success or a negative error code on failure in creating a random number generator. Currently, the following error codes can be returned.

`QSMM_ERR_INVAL`

Argument

`rng_p`is`NULL`

.`QSMM_ERR_NOMEM`

There was not enough memory to create a random number generator.

By default, the `configure` script configures the package to use a pseudorandom number generator implemented by the function `rand`

from the standard C library, as the standard random number generator.
This mode of operation does not require dependency on an external library but is not recommended.
The recommended mode is to use a pseudorandom number generator provided by the GNU Scientific Library, as the standard random number generator.
See the file `INSTALL` in the root of the package distribution for information on how to configure the package to use that library.

One of disadvantages of using a pseudorandom number generator implemented by the function `rand`

from the standard C library is that only one instance of the pseudorandom number generator exists, and different handles will actually correspond to a single pseudorandom number generator.
This will cause problems when seeding pseudorandom number generators represented by different handles.

A function described below can be used to create a random number generator on the basis of a user-supplied function.

- Function:
*int***qsmm_rng_create_custom***(qsmm_proxy_func_t*`rng_func`, void *`paramp`, qsmm_rng_t *`rng_p`) This function creates a random number generator on the basis of function

`rng_func`and its parameter`paramp`and stores a newly allocated handle of the random number generator in *`rng_p`. Function`rng_func`must implement an interface for abstract random number generator. See Custom Random Number Generators, for a description of the interface.The function returns a non-negative value on success or a negative error code on failure in creating a random number generator. Currently, the following error codes can be returned.

`QSMM_ERR_INVAL`

Argument

`rng_p`is`NULL`

.`QSMM_ERR_NOMEM`

There was not enough memory to create a random number generator.

To destroy a random number generator, the following function can be used.

- Function:
*void***qsmm_rng_destroy***(qsmm_rng_t*`rng`) This function destroys a random number generator specified by handle

`rng`. After destruction of the random number generator, the handle must not be used. If`rng`is`NULL`

, then the function will have no effect.An application program is only allowed to destroy random number generators, which it has created explicitly by the function

`qsmm_rng_create`

or`qsmm_rng_create_custom`

. For example, if the application program destroys a random number generator, which was automatically created for a multinode model and returned by the function`qsmm_get_rng`

, then a segmentation fault will occur later.

Next: Generating Random Numbers, Up: Random Number Generators [Contents][Index]