eio: add method for determining if a monitor is using the fallback mechanism

the fallback method of calling stat() on the monitored paths does not allow
for various eio events to be emitted, meaning that any application which relies
on those events can never receive them

this provides a method for checking a monitor to determine which functionality
is available, and also provides more explicit documentation regarding events
that are not provided by fallback monitoring

this method is marked as beta

@feature

Differential Revision: https://phab.enlightenment.org/D6447

src/lib/eio/Eio_Legacy.h

@@ -1174,12 +1174,12 @@ EAPI Eio_File *eio_eet_write_cipher(Eet_File *ef,
 EAPI extern int EIO_MONITOR_FILE_CREATED; /**< A new file was created in a watched directory */
 EAPI extern int EIO_MONITOR_FILE_DELETED; /**< A watched file was deleted, or a file in a watched directory was deleted */
 EAPI extern int EIO_MONITOR_FILE_MODIFIED; /**< A file was modified in a watched directory */
-EAPI extern int EIO_MONITOR_FILE_CLOSED; /**< A file was closed in a watched directory. This event is never sent on Windows and OSX */
+EAPI extern int EIO_MONITOR_FILE_CLOSED; /**< A file was closed in a watched directory. This event is never sent on Windows and OSX, or for non-fallback monitors */
 EAPI extern int EIO_MONITOR_DIRECTORY_CREATED; /**< A new directory was created in a watched directory */
 EAPI extern int EIO_MONITOR_DIRECTORY_DELETED; /**< A directory has been deleted: this can be either a watched directory or one of its subdirectories */
 EAPI extern int EIO_MONITOR_DIRECTORY_MODIFIED; /**< A directory has been modified in a watched directory */
-EAPI extern int EIO_MONITOR_DIRECTORY_CLOSED; /**< A directory has been closed in a watched directory. This event is never sent on Windows and OSX */
-EAPI extern int EIO_MONITOR_SELF_RENAME; /**< The monitored path has been renamed, an error could happen just after if the renamed path doesn't exist. This event is never sent on OSX */
+EAPI extern int EIO_MONITOR_DIRECTORY_CLOSED; /**< A directory has been closed in a watched directory. This event is never sent on Windows and OSX, or for non-fallback monitors */
+EAPI extern int EIO_MONITOR_SELF_RENAME; /**< The monitored path has been renamed, an error could happen just after if the renamed path doesn't exist. This event is never sent on OSX, or for non-fallback monitors */
 EAPI extern int EIO_MONITOR_SELF_DELETED; /**< The monitored path has been removed. This event is never sent on OSX */
 EAPI extern int EIO_MONITOR_ERROR; /**< During operation the monitor failed and will no longer work. eio_monitor_del must be called on it. */
 
@@ -1241,6 +1241,20 @@ EAPI void eio_monitor_del(Eio_Monitor *monitor);
  */
 EAPI const char *eio_monitor_path_get(Eio_Monitor *monitor);
 
+#ifdef EFL_BETA_API_SUPPORT
+/**
+ * @brief Check whether a monitor is using the fallback backend
+ * @param monitor The Eio_Monitor to check
+ * @return EINA_TRUE only if the monitor is valid and is using the fallback monitoring mechanism
+ *
+ * Fallback monitors are unable to provide the CLOSED or RENAME events. It's important
+ * to check whether a monitor is a fallback monitor before relying on these events.
+ *
+ * @since 1.21
+ * @beta
+ */
+EAPI Eina_Bool eio_monitor_fallback_check(const Eio_Monitor *monitor);
+#endif
 /**
  * @}
  */

src/lib/eio/eio_monitor_poll.c

@@ -391,3 +391,10 @@ eio_monitoring_interval_set(double interval)
      ecore_timer_interval_set(timer, fallback_interval);
    eina_iterator_free(it);
 }
+
+EAPI Eina_Bool
+eio_monitor_fallback_check(const Eio_Monitor *monitor)
+{
+   EINA_SAFETY_ON_NULL_RETURN_VAL(monitor, EINA_FALSE);
+   return monitor->fallback;
+}

src/lib/eio/eio_sentry.c

@@ -21,6 +21,7 @@
 # include <config.h>
 #endif
 
+#define EIO_SENTRY_BETA 1
 
 #include <Eo.h>
 #include "Ecore.h"
@@ -145,6 +146,19 @@ _eio_sentry_remove(Eo *obj EINA_UNUSED, Eio_Sentry_Data *pd, const char *path)
    eina_hash_del(pd->targets, path, NULL);
 }
 
+Eina_Bool
+_eio_sentry_fallback_check(const Eo *obj EINA_UNUSED, Eio_Sentry_Data *pd, const char *path)
+{
+   Eio_Monitor *monitor;
+
+   EINA_SAFETY_ON_NULL_RETURN_VAL(path, EINA_FALSE);
+   EINA_SAFETY_ON_NULL_RETURN_VAL(pd, EINA_FALSE);
+
+   monitor = eina_hash_find(pd->targets, path);
+   EINA_SAFETY_ON_NULL_RETURN_VAL(monitor, EINA_FALSE);
+   return eio_monitor_fallback_check(monitor);
+}
+
 Efl_Object * _eio_sentry_efl_object_constructor(Eo *obj, Eio_Sentry_Data *pd)
 {
    obj = efl_constructor(efl_super(obj, EIO_SENTRY_CLASS));

src/lib/eio/eio_sentry.eo

@@ -23,17 +23,27 @@ class Eio.Sentry (Efl.Object)
         @in path: string; [[Path to remove from monitoring]]
       }
     }
+    fallback_check @const @beta {
+      [[Return if the sentry is using the fallback monitoring method
+
+        The fallback method of monitoring cannot provide certain events.
+      ]]
+      params {
+        @in path: string; [[Path to check for fallback monitoring]]
+      }
+      return : bool; [[$true only if the sentry is using the fallback mechanism]]
+    }
   }
  events {
     file,created: Eio.Sentry.Event; [[Called when a file was created]]
     file,deleted: Eio.Sentry.Event; [[Called when a file was deleted]]
     file,modified: Eio.Sentry.Event; [[Called when a file was modified]]
-    file,closed: Eio.Sentry.Event; [[Called when a file was closed]]
+    file,closed: Eio.Sentry.Event; [[Called for non-fallback sentries when a file was closed]]
     directory,created: Eio.Sentry.Event; [[Called when a directory was created]]
     directory,deleted: Eio.Sentry.Event; [[Called when a directory was deleted]]
     directory,modified: Eio.Sentry.Event; [[called when a directory was modified]]
-    directory,closed: Eio.Sentry.Event; [[Called when a directory was closed]]
-    self,rename: Eio.Sentry.Event; [[Called when the object was renamed]]
+    directory,closed: Eio.Sentry.Event; [[Called for non-fallback sentries when a directory was closed]]
+    self,rename: Eio.Sentry.Event; [[Called for non-fallback sentries when the object was renamed]]
     self,deleted: Eio.Sentry.Event; [[Called when the object was deleted]]
     error: Eio.Sentry.Event; [[Called in case of an error]]
  }