Move more rig_cache infrastructure to cache.[ch]

Macros from rig.h, routines from misc.c
Add some error checks and comments

include/hamlib/rig.h

@@ -2522,7 +2522,7 @@ typedef hamlib_port_t port_t;
 #define RIGPORT(r) (&r->state.rigport)
 #define PTTPORT(r) (&r->state.pttport)
 #define DCDPORT(r) (&r->state.dcdport)
-#define CACHE(r) ((r)->cache_addr)
+//Moved to cache.h #define CACHE(r) ((r)->cache_addr)
 #define AMPPORT(a) (&a->state.ampport)
 #define ROTPORT(r) (&r->state.rotport)
 #define ROTPORT2(r) (&r->state.rotport2)
@@ -2539,7 +2539,7 @@ typedef hamlib_port_t port_t;
 #define HAMLIB_RIGPORT(r) ((hamlib_port_t *)rig_data_pointer(r, RIG_PTRX_RIGPORT))
 #define HAMLIB_PTTPORT(r) ((hamlib_port_t *)rig_data_pointer(r, RIG_PTRX_PTTPORT))
 #define HAMLIB_DCDPORT(r) ((hamlib_port_t *)rig_data_pointer(r, RIG_PTRX_DCDPORT))
-#define HAMLIB_CACHE(r) ((struct rig_cache *)rig_data_pointer(r, RIG_PTRX_CACHE))
+//#define HAMLIB_CACHE(r) ((struct rig_cache *)rig_data_pointer(r, RIG_PTRX_CACHE))
 #define HAMLIB_AMPPORT(a) ((hamlib_port_t *)amp_data_pointer(a, RIG_PTRX_AMPPORT))
 #define HAMLIB_ROTPORT(r) ((hamlib_port_t *)rot_data_pointer(r, RIG_PTRX_ROTPORT))
 #define HAMLIB_ROTPORT2(r) ((hamlib_port_t *)rot_data_pointer(r, RIG_PTRX_ROTPORT2))

src/cache.c

@@ -310,8 +310,8 @@ int rig_set_cache_freq(RIG *rig, vfo_t vfo, freq_t freq)
 int rig_get_cache(RIG *rig, vfo_t vfo, freq_t *freq, int *cache_ms_freq,
                   rmode_t *mode, int *cache_ms_mode, pbwidth_t *width, int *cache_ms_width)
 {
-    struct rig_cache *cachep = CACHE(rig);
-    struct rig_state *rs = STATE(rig);
+    struct rig_cache *cachep;
+    struct rig_state *rs;
 
     if (CHECK_RIG_ARG(rig) || !freq || !cache_ms_freq ||
             !mode || !cache_ms_mode || !width || !cache_ms_width)
@@ -319,6 +319,9 @@ int rig_get_cache(RIG *rig, vfo_t vfo, freq_t *freq, int *cache_ms_freq,
         return -RIG_EINVAL;
     }
 
+    cachep = CACHE(rig);
+    rs = STATE(rig);
+
     if (rig_need_debug(RIG_DEBUG_CACHE))
     {
         ENTERFUNC2;
@@ -565,6 +568,25 @@ int rig_get_cache_freq(RIG *rig, vfo_t vfo, freq_t *freq, int *cache_ms_freq_p)
     return retval;
 }
 
+/* Get cache timeout period
+ * Returns value in msec, -1 if error
+ */
+int HAMLIB_API rig_get_cache_timeout_ms(RIG *rig, hamlib_cache_t selection)
+{
+    rig_debug(RIG_DEBUG_TRACE, "%s: called selection=%d\n", __func__, selection);
+    if (!rig) {return -1;}
+    return CACHE(rig)->timeout_ms;
+}
+
+int HAMLIB_API rig_set_cache_timeout_ms(RIG *rig, hamlib_cache_t selection,
+                                        int ms)
+{
+    rig_debug(RIG_DEBUG_TRACE, "%s: called selection=%d, ms=%d\n", __func__,
+              selection, ms);
+    if (!rig) {return -RIG_EINVAL;}
+    CACHE(rig)->timeout_ms = ms;
+    return RIG_OK;
+}
 
 void rig_cache_show(RIG *rig, const char *func, int line)
 {

src/cache.h

@@ -28,6 +28,14 @@
 
 __BEGIN_DECLS
 
+/* It should be noted that there are two distinct cache implementations
+ * in Hamlib.  This one is for the app-facing side, providing cached status
+ * (freq, mode, band, etc) for application queries. The other is used by
+ * backends for rig status probes, watchdog timers, and other hardware related
+ * tasks. Also note that they use different times - timespec vs timeval.
+ *      - n3gb 2025-05-14
+ */
+
 /**
  * \brief Rig cache data
  *
@@ -108,6 +116,13 @@ struct rig_cache {
     int satmode; // if rig is in satellite mode
 };
 
+/* Access macros */
+#define CACHE(r) ((r)->cache_addr)
+//#define HAMLIB_CACHE(r) ((struct rig_cache *)rig_data_pointer(r, RIG_PTRX_CACHE))
+
+/* Function templates
+ * Does not include those marked as part of HAMLIB_API
+ */
 int rig_set_cache_mode(RIG *rig, vfo_t vfo, rmode_t mode, pbwidth_t width);
 int rig_set_cache_freq(RIG *rig, vfo_t vfo, freq_t freq);
 void rig_cache_show(RIG *rig, const char *func, int line);

src/misc.c

@@ -1967,6 +1967,7 @@ double HAMLIB_API elapsed_ms(struct timespec *start, int option)
         break;
     }
 
+    // Casts used to make sure the add is done as double
     elapsed_msec = (double)((stop.tv_sec - start->tv_sec) * 1000) + // sec -> ms
                    (double)(stop.tv_nsec - start->tv_nsec) / 1e6;   // ns  -> ms
 
@@ -1978,22 +1979,6 @@ double HAMLIB_API elapsed_ms(struct timespec *start, int option)
 }
 //! @endcond
 
-
-int HAMLIB_API rig_get_cache_timeout_ms(RIG *rig, hamlib_cache_t selection)
-{
-    rig_debug(RIG_DEBUG_TRACE, "%s: called selection=%d\n", __func__, selection);
-    return CACHE(rig)->timeout_ms;
-}
-
-int HAMLIB_API rig_set_cache_timeout_ms(RIG *rig, hamlib_cache_t selection,
-                                        int ms)
-{
-    rig_debug(RIG_DEBUG_TRACE, "%s: called selection=%d, ms=%d\n", __func__,
-              selection, ms);
-    CACHE(rig)->timeout_ms = ms;
-    return RIG_OK;
-}
-
 static char *funcname = "Unknown";
 static int linenum = 0;