Next: Generating Random Numbers, Up: Random Number Generators [Contents][Index]
A random number generator handle refers to a random number generator.
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.
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.
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.
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]