Procedure

     SWPOOL ( Set watch on a pool variable )

     ENTRY SWPOOL ( AGENT, NNAMES, NAMES )

Abstract

     Add a name to the list of agents to notify whenever a member of
     a list of kernel variables is updated.

Required_Reading

     KERNEL

Keywords

     CONSTANTS
     FILES

Declarations

    CHARACTER*(*)         AGENT
    INTEGER               NNAMES
    CHARACTER*(*)         NAMES  ( * )

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     AGENT      I   The name of an agent to be notified after updates.
     NNAMES     I   The number of variables to associate with AGENT.
     NAMES      I   Variable names whose update causes the notice.

Detailed_Input

     AGENT    is the name of a routine or entry point (agency) that
              will want to know when the kernel pool variables
              designated by NAMES have been updated.

     NNAMES   is the number of kernel pool variable names that will
              be associated with AGENT.

     NAMES    is an array of names of variables in the kernel pool.
              Whenever any of these is updated, a notice will be
              posted for AGENT so that one can quickly check
              whether needed data has been modified.

              Any kernel variable may be associated with multiple
              agents; this call adds AGENT to each set of agents
              associated with a member of NAMES.

              The variables designated by NAMES need not exist in
              the kernel pool at the time a watch is set.

Detailed_Output

     None.

Parameters

     None.

Exceptions

     1)  If sufficient room is not available to hold a new kernel
         variable name, the error SPICE(KERVARSETOVERFLOW) is signaled.

     2)  If sufficient room is not available to hold a new agent
         name, the error SPICE(TOOMANYWATCHES) is signaled.

     3)  If any kernel variable in the array NAMES is already watched
         by MAXAGT agents, and AGENT is not already associated with
         that kernel variable, the error SPICE(AGENTLISTOVERFLOW) is
         signaled.

Files

     None.

Particulars

     The kernel pool is a convenient place to store a wide
     variety of data needed by routines in SPICELIB and routines
     that interface with SPICELIB routines. However, when
     a single name has a large quantity of data associated with
     it, it becomes inefficient to constantly query the kernel
     pool for values that are not updated on a frequent basis.

     This entry point allows a routine to instruct the kernel pool
     to post a message whenever a particular value gets updated.
     In this way, a routine can quickly determine whether or not
     data it requires has been updated since the last time the
     data was accessed. This makes it reasonable to buffer
     the data in local storage and update it only when
     a variable in the kernel pool that affects this data has
     been updated.

     Note that SWPOOL has a side effect. Whenever a call to
     SWPOOL is made, the agent specified in the calling sequence
     is added to the list of agents that should be notified that
     an update of its variables has occurred. In other words
     the code

         CALL SWPOOL ( AGENT, NNAMES, NAMES  )
         CALL CVPOOL ( AGENT,         UPDATE )

     will always return UPDATE as .TRUE.

     This feature allows for a slightly cleaner use of SWPOOL and
     CVPOOL as shown in the example below. Because SWPOOL
     automatically loads AGENT into the list of agents to notify of
     a kernel pool update, you do not have to include the code for
     fetching the initial values of the kernel variables in the
     initialization portion of a subroutine. Instead, the code for
     the first fetch from the pool is the same as the code for
     fetching when the pool is updated.

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

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     B.V. Semenov       (JPL)
     W.L. Taber         (JPL)

Version

    SPICELIB Version 8.2.1, 17-AUG-2021 (JDR)

        Edited the header to comply with NAIF standard.

    SPICELIB Version 8.2.0, 30-JUL-2013 (BVS)

        Updated to increment POOL state counter.

    SPICELIB Version 8.1.0, 19-MAR-2009 (NJB)

        This routine was re-written to work with the new
        watcher system implementation. Several bugs related
        to watch system overflow were fixed.

        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.