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


6.1.1 Creating a Random Number Generator

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