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

A random number generator handle refers to a random number generator.

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

`NULL`

. The functions`qsmm_rng_create`

and`qsmm_rng_create_custom`

allocate a new handle. The function`qsmm_rng_destroy`

frees an existing handle.You can pass an allocated handle to API functions taking an argument of

`qsmm_rng_t`

type until freeing the handle. You can also set an allocated handle as the value of`rng`

field of`qsmm_actor_desc_s`

or`qsmm_desc_s`

structure specifying the parameters of creating an actor or multinode model respectively. The lifetime of an allocated handle should be longer than the lifetime of an actor or multinode model.

The function `qsmm_get_actor_rng`

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

of `qsmm_actor_desc_s`

structure when creating an actor by the function `qsmm_actor_create`

or returns the handle of an instance of default random number generator allocated automatically if that field was `NULL`

.
The function `qsmm_get_rng`

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

of `qsmm_desc_s`

structure when creating a multinode model by the function `qsmm_create`

or returns the handle of an instance of default random number generator allocated automatically if that field was `NULL`

.

Use the following function to create a random number generator as an instance of default random number generator.

- 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 with a type defined by a user-supplied function`qsmm_proxy_func_t`

and its parameter set by a call to the function`qsmm_set_rng_default`

(see Custom Random Number Generators) or a random number generator with a standard type defined when configuring the package if the user-supplied function 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 function can return the following error codes.

`QSMM_ERR_INVAL`

The argument

`rng_p`is`NULL`

.`QSMM_ERR_NOMEM`

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

In default and recommended mode, the `configure` script configures the package to use a pseudo-random number generator provided by the GNU Scientific Library as a standard random number generator.
In the other mode, the `configure` script configures the package to use a pseudo-random number generator implemented by the function `rand`

from the standard C library.
The latter mode does not require dependency on the external library.
See the file `INSTALL` in the root of the package distribution for how to specify the latter mode for the `configure` script.

One of disadvantages of using a pseudo-random number generator implemented by `rand`

is that only one instance of this pseudo-random number generator exists, and different handles actually refer to this single instance causing problems when seeding pseudo-random number generators represented by different handles.

Use the function described below to create a random number generator based on 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 based on a function

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

`QSMM_ERR_INVAL`

The argument

`rng_p`is`NULL`

.`QSMM_ERR_NOMEM`

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

Use the following function to destroy a random number generator.

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

`rng`. You must not use the handle after the destruction of this random number generator. If`rng`is`NULL`

, the function has no effect.An application program may only destroy random number generators it created explicitly by the function

`qsmm_rng_create`

or`qsmm_rng_create_custom`

. For example, if the application program destroys a random number generator implicitly allocated for a multinode model on its creation and returned by the function`qsmm_get_rng`

, a memory error occurs later.

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