pub fn cvpool(
ctx: &mut SpiceContext<'_>,
agent: &str,
update: &mut bool,
) -> Result<()>Expand description
Check variable in the pool for update
Indicate whether or not any watched kernel variables that have a specified agent on their notification list have been updated.
§Required Reading
§Brief I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
AGENT I Name of the agent to check for notices.
UPDATE O .TRUE. if variables for AGENT have been updated.§Detailed Input
AGENT is the name of a subroutine, entry point, or significant
portion of code that needs to access variables in the
kernel pool. Generally this agent will buffer these
variables internally and fetch them from the kernel
pool only when they are updated.§Detailed Output
UPDATE is a logical flag that will be set to .TRUE. if the
variables in the kernel pool that are associated with
AGENT have been updated since the last call to CVPOOL.
UPDATE will be set to .TRUE. on the first call made for
the specified agent, whether or not the associated
variables have been updated since the agent was placed
on their notification list, as long as the agent is
associated with any watched variables.§Parameters
See the umbrella subroutine POOL.§Particulars
This entry point allows the calling program to determine
whether or not variables associated with with AGENT have
been updated. Making use of this entry point in conjunction
with the entry point SWPOOL (set watch on pool variables)
modules can buffer kernel pool variables they need and
fetch values from the kernel pool only when variables have
been updated.
Note that the call to CVPOOL has a side effect.
Two consecutive calls to CVPOOL with the same
AGENT will always result in the UPDATE being .FALSE.
on the second call. In other words, if you embed
the following two lines of code in a piece of code
CALL CVPOOL ( AGENT, UPDATE )
CALL CVPOOL ( AGENT, UPDATE )
and then test UPDATE, it will be .FALSE. The idea is
that once a call to CVPOOL has been made, the
kernel pool has performed its duty and notified the
calling routine that one of the AGENT's variables
has been updated. Consequently, on the second call
to CVPOOL above, the kernel pool will not have any
updates to report about any of AGENT's variables.
If, on the other hand, you have code such as
CALL CVPOOL ( AGENT, UPDATE )
CALL LDPOOL ( 'MYFILE.DAT' )
CALL CVPOOL ( AGENT, UPDATE )
the value of UPDATE will be true if one of the variables
associated with AGENT was updated by the call to
LDPOOL (and that variable has been specified as one
to watch by call a call to SWPOOL).
It should also be noted that any call to CVPOOL that
occurs immediately after a call to SWPOOL will result in
UPDATE being returned as .TRUE. In other words, code
such as shown below, will always result in the value
of UPDATE as being returned .TRUE.
CALL SWPOOL ( AGENT, NNAMES, NAMES )
CALL CVPOOL ( AGENT, UPDATE )
See the header for SWPOOL for a full discussion of this
feature.§Examples
Suppose that you have an application subroutine, MYTASK, that
needs to access a large data set in the kernel pool. If this
data could be kept in local storage and kernel pool queries
performed only when the data in the kernel pool has been
updated, the routine can perform much more efficiently.
The code fragment below illustrates how you might make use of this
feature.
C
C On the first call to this routine establish those variables
C that we will want to read from the kernel pool only when
C new values have been established.
C
IF ( FIRST ) THEN
FIRST = .FALSE.
HAVE = .FALSE.
CALL SWPOOL ( 'MYTASK', NNAMES, NAMES )
END IF
C
C If any of the variables has been updated, fetch
C it from the kernel pool. (Note that this also
C handles getting variables for the first time.)
C We use HAVE to indicate the fetch succeeded. If it
C didn't, we need to attempt the fetch on the next
C pass into this routine.
C
CALL CVPOOL ( 'MYTASK', UPDATE )
IF ( UPDATE .OR (.NOT. HAVE ) ) THEN
CALL GDPOOL ( 'MYTASK_VAR_1', 1, M, N1, VALS1, FOUND(1) )
CALL GDPOOL ( 'MYTASK_VAR_2', 1, M, N2, VALS2, FOUND(2) )
.
.
.
CALL GDPOOL ( 'MYTASK_VAR_N', 1, M, NN, VALSN, FOUND(N) )
END IF
IF ( FAILED() ) THEN
.
.
do something about the failure
.
.
ELSE
HAVE = .TRUE.
END IF§Author and Institution
N.J. Bachman (JPL)
J. Diaz del Rio (ODC Space)
W.L. Taber (JPL)§Version
- SPICELIB Version 8.1.2, 17-AUG-2021 (JDR)
Edited the header to comply with NAIF standard.
- SPICELIB Version 8.1.1, 30-JUN-2014 (NJB)
Description of the output variable UPDATE now
mentions that the initial value of .TRUE. will
be returned after an agent is associated with
kernel variables.
- SPICELIB Version 8.1.0, 19-MAR-2009 (NJB)
ZZPINI call was updated for compatibility
with new watcher system implementation.
The code example was updated to handle kernel pool
fetch failure.
- SPICELIB Version 8.0.0, 04-JUN-1999 (WLT)
Added the entry points PCPOOL, PDPOOL and PIPOOL to allow
direct insertion of data into the kernel pool without having
to read an external file.
Added the interface LMPOOL that allows SPICE
programs to load text kernels directly from memory
instead of requiring a text file.
Added the entry point SZPOOL to return kernel pool definition
parameters.
Added the entry point DVPOOL to allow the removal of a variable
from the kernel pool.
Added the entry point GNPOOL to allow users to determine
variables that are present in the kernel pool
- SPICELIB Version 7.0.0, 20-SEP-1995 (WLT)
The implementation of the kernel pool was completely redone
to improve performance in loading and fetching data. In
addition the pool was upgraded so that variables may be
either string or numeric valued.
- SPICELIB Version 6.0.0, 31-MAR-1992 (WLT)
The entry points SWPOOL and CVPOOL were added.§Revisions
- SPICELIB Version 8.1.0, 19-MAR-2009 (NJB)
ZZPINI call was updated for compatibility
with new watcher system implementation.
- SPICELIB Version 8.0.0, 04-JUN-1999 (WLT)
Added the entry points PCPOOL, PDPOOL and PIPOOL to allow
direct insertion of data into the kernel pool without having
to read an external file.
Added the interface LMPOOL that allows SPICE
programs to load text kernels directly from memory
instead of requiring a text file.
Added the entry point SZPOOL to return kernel pool definition
parameters.
Added the entry point DVPOOL to allow the removal of a variable
from the kernel pool.
Added the entry point GNPOOL to allow users to determine
variables that are present in the kernel pool
- SPICELIB Version 7.0.0, 20-SEP-1995 (WLT)
The implementation of the kernel pool was completely redone
to improve performance in loading and fetching data. In
addition the pool was upgraded so that variables may be
either string or numeric valued.
The basic data structure used to maintain the list of
variable names and values was replaced with a hash table
implementation. Data and names are accessed by means
of a hash function and linked lists of pointers to existing
variable names and data values.
- SPICELIB Version 6.0.0, 31-MAR-1992 (WLT)
The entry points SWPOOL (set watch on a pool variable)
and CVPOOL (check variable for update) so that routines
that buffer data stored in the kernel pool can fetch
that data only when it is updated.
In addition, the revision history was upgraded so that the
version number increases over time. This wasn't true
before. In addition some early revision data that referred to
pre-SPICELIB modifications were removed. This editing of
the version numbers makes it unlikely that anyone can track
down which previous version of this routine they have by
looking at the version number. The best way to determine
the routine you had previously is to compare the dates
stored in the Version line of the routine.