\name{NeticaRNG-class}
\Rdversion{1.1}
\docType{class}
\alias{NeticaRNG-class}
\alias{print,NeticaRNG-method}
\alias{toString,NeticaRNG-method}
\alias{as.character,NeticaRNG-method}

\title{Class \code{"NeticaRNG"}}
\description{
  This is an object containing a reference to a Netica Random Number
  Generator. Note that the storage for NeticaRNG objects should be
  freed when you are done with them by calling
  \code{\link{FreeNeticaRNG}(\var{rng})}. 

}
\section{Extends}{

All reference classes extend and inherit methods from
\code{"\linkS4class{envRefClass}"}. Note that because this is a
reference class unlike traditional S3 and S4 classes it can be
destructively modified.  Also fields (slots) are accessed using the
\sQuote{$} operator.

}
\section{Methods}{
  \describe{
    \item{print}{\code{signature(x = "NeticaRNG")}: Produces a printer
      representation of the RNG object. }
    \item{toString}{\code{signature(x = "NeticaRNG")}: Produces a string
    representation of the RNG object.}
}
}
\details{

  Netica supports random number generator objects which serve can be
  used to generate random cases (\code{\link{GenerateRandomCase}()}).
  In either case explicitly creating a random number generator is
  optional.  If this is not done, the default random number generator is
  uses, which is slightly slower because it needs to be threadsafe.  As
  RNetica probably adds more overhead than the non-threadsafe RNG, the
  primary use for creating a NeticaRNG is to produce a reproducable
  sequence of random cases.

  Creating a random number generator with \code{\var{rng} <-
  NewNeticaRNG(\var{seed})} generates an object in Netica space.  The memory
  for that object should be freed when that is complete.  The expression
  \code{FreeNeticaRNG(\var{rng})} frees this object.  The function
  \code{WithRNG} can be used to execute code in a context where the RNG
  will be freed after after completion or in the case of early
  termination due to an error.  

  When the random number generator is freed, or if the R session or
  Netica session is terminated, the NeticaRNG object will become
  inactive.   The function \code{isNeticaRNGActive(\var{rng})} tests to see if
  the random number generator is active (the Netica version still
  exists).  
  
}
\references{
  \newcommand{\nref}{\href{http://norsys.com/onLineAPIManual/functions/#1.html}{#1()}}
  \url{http://norsys.com/onLineAPIManual/index.html}:
  \nref{NewRandomGenerator_ns},
  \nref{DeleteRandomGen_ns}
  \url{http://homepage.stat.uiowa.edu/~luke/R/references/weakfinex.html}
}
\author{Russell Almond}
\note{

  There are two other uses of newly created Netica RNG objects in the
  Netica Manual which are not currently supported by RNetica.  One is to
  simply generate uniform random numbers which seems superfluous given
  R's richer random number generation facilities.  The second it to
  associate the RNG with a network.  According to the manual, such RNGs
  no longer need to be deleted when you are done with them.  This seems
  like it could lead to a situation where a single RNG was associated
  with two networks and then the RNG was deleted when the first network
  was deleted.  Therefore the function \code{\link{NetworkSetRNG}()}
  always creates a new RNG.

  Internally, a weak reference system is used to keep a list of Netica
  RNG objects which need to be closed when RNetica is unloaded.
  RNG objects should also be forced closed when garbage collected.
  The weak reference system is somewhat experimental, so well designed
  code should manually close the RNG when the program is through
  with it.
}

\seealso{
  An object of \code{NeticaRNG} which is produced
  by a call to \code{\link{NewNeticaRNG}}.

  \code{\link{NetworkSetRNG}()}, \code{\link{GenerateRandomCase}()}

}
\examples{

sess <- NeticaSession()
startSession(sess)

rng <- NewNeticaRNG(123456789,sess)

stopifnot(is.NeticaRNG(rng),
          isNeticaRNGActive(rng))

FreeNeticaRNG(rng)
stopifnot(!isNeticaRNGActive(rng))

stopSession(sess)


}
\keyword{ interface }
\keyword{ datagen }
\keyword{classes}
\section{Fields}{
  Note these should be regarded as read-only from user code.
  \describe{
    \item{\code{Name}:}{Object of class \code{character} giving a name
      to the RNG.  These are autogenerated with a number. }
    \item{\code{Session}:}{Object of class \code{NeticaSession} : a back
      pointer to the \code{\linkS4class{NeticaSession}} object in which
      the network was created. }
    \item{\code{Netica_RNG}:}{Object of class \code{externalptr} which
      hold the pointer to the RNG object in the Netica workspace. }
    \item{\code{Seed}:}{Object of class \code{integer} giving the seed
      used to initialize the RNG. }
  }
}
\section{Class-Based Methods}{
  \describe{
    \item{\code{show()}:}{ Provides a printed description }
    \item{\code{free()}:}{ Frees the RNG in Netica Memory.  Equivalent
      to \code{\link{FreeNeticaRNG}}. }
    \item{\code{isActive()}:}{ Test to see if the RNG is active (been
      created in Netica) or inactive (already freed). }
    \item{\code{clearErrors(severity)}:}{ Calls \code{clearErrors} on
      the \code{Session} object. }
    \item{\code{reportErrors(maxreport, clear)}:}{ Calls
      \code{reportErrors} on the \code{Session} object. }
    \item{\code{initialize(Name, Session, Seed, ...)}:}{ Initialization
      function.  Should not be called by user code. }
  }
}