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


6.1.1 Creating a Random Number Generator

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: , Up: Random Number Generators   [Contents][Index]