Add support for RedisModule_CreateTimer (#67)

* Add support for Redis timers

- Wrappers for RedisModule_CreateTimer, StopTimer and GetTimerInfo.
- Type-safe handling of user-supplied data and callback.
- Ownership of data is handled using Rust's ownership semantics.

Author: gavrie

Cargo.toml

@@ -17,6 +17,11 @@ crate-type = ["cdylib"]
 name = "keys_pos"
 crate-type = ["cdylib"]
 
+[[example]]
+name = "timer"
+crate-type = ["cdylib"]
+required-features = ["experimental-api"]
+
 [[example]]
 name = "data_type"
 crate-type = ["cdylib"]

examples/timer.rs

@@ -0,0 +1,54 @@
+#[macro_use]
+extern crate redis_module;
+
+use redis_module::{Context, NextArg, RedisError, RedisResult};
+use std::time::Duration;
+
+fn callback(ctx: &Context, data: String) {
+    ctx.log_debug(format!("[callback]: {}", data).as_str());
+}
+
+type MyData = String;
+
+fn timer_create(ctx: &Context, args: Vec<String>) -> RedisResult {
+    let mut args = args.into_iter().skip(1);
+    let duration = args.next_i64()?;
+    let data: MyData = args.next_string()?;
+
+    let timer_id = ctx.create_timer(Duration::from_millis(duration as u64), callback, data);
+
+    return Ok(format!("{}", timer_id).into());
+}
+
+fn timer_info(ctx: &Context, args: Vec<String>) -> RedisResult {
+    let mut args = args.into_iter().skip(1);
+    let timer_id = args.next_u64()?;
+
+    let (remaining, data): (_, &MyData) = ctx.get_timer_info(timer_id)?;
+    let reply = format!("Remaining: {:?}, data: {:?}", remaining, data);
+
+    return Ok(reply.into());
+}
+
+fn timer_stop(ctx: &Context, args: Vec<String>) -> RedisResult {
+    let mut args = args.into_iter().skip(1);
+    let timer_id = args.next_u64()?;
+
+    let data: MyData = ctx.stop_timer(timer_id)?;
+    let reply = format!("Data: {:?}", data);
+
+    return Ok(reply.into());
+}
+
+//////////////////////////////////////////////////////
+
+redis_module! {
+    name: "timer",
+    version: 1,
+    data_types: [],
+    commands: [
+        ["timer.create", timer_create, "", 0, 0, 0],
+        ["timer.info", timer_info, "", 0, 0, 0],
+        ["timer.stop", timer_stop, "", 0, 0, 0],
+    ],
+}

src/context.rs src/context/mod.rssrc/context.rs renamed to src/context/mod.rs

@@ -7,10 +7,13 @@ use crate::raw;
 use crate::LogLevel;
 use crate::{RedisError, RedisResult, RedisString, RedisValue};
 
+#[cfg(feature = "experimental-api")]
+mod timer;
+
 /// `Context` is a structure that's designed to give us a high-level interface to
 /// the Redis module API by abstracting away the raw C FFI calls.
 pub struct Context {
-    ctx: *mut raw::RedisModuleCtx,
+    pub(crate) ctx: *mut raw::RedisModuleCtx,
 }
 
 impl Context {

src/context/timer.rs

@@ -0,0 +1,132 @@
+use std::convert::TryInto;
+use std::ffi::c_void;
+use std::time::Duration;
+
+use crate::raw;
+use crate::raw::RedisModuleTimerID;
+use crate::{Context, RedisError};
+
+// We use `repr(C)` since we access the underlying data field directly.
+// The order matters: the data field must come first.
+#[repr(C)]
+struct CallbackData<F: FnOnce(&Context, T), T> {
+    data: T,
+    callback: F,
+}
+
+impl Context {
+    /// Wrapper for `RedisModule_CreateTimer`.
+    ///
+    /// This function takes ownership of the provided data, and transfers it to Redis.
+    /// The callback will get the original data back in a type safe manner.
+    /// When the callback is done, the data will be dropped.
+    pub fn create_timer<F, T>(&self, period: Duration, callback: F, data: T) -> RedisModuleTimerID
+    where
+        F: FnOnce(&Context, T),
+    {
+        let cb_data = CallbackData { data, callback };
+
+        // Store the user-provided data on the heap before passing ownership of it to Redis,
+        // so that it will outlive the current scope.
+        let data = Box::from(cb_data);
+
+        // Take ownership of the data inside the box and obtain a raw pointer to pass to Redis.
+        let data = Box::into_raw(data);
+
+        let timer_id = unsafe {
+            raw::RedisModule_CreateTimer.unwrap()(
+                self.ctx,
+                period
+                    .as_millis()
+                    .try_into()
+                    .expect("Value must fit in 64 bits"),
+                Some(raw_callback::<F, T>),
+                data as *mut c_void,
+            )
+        };
+
+        timer_id
+    }
+
+    /// Wrapper for `RedisModule_StopTimer`.
+    ///
+    /// The caller is responsible for specifying the correct type for the returned data.
+    /// This function has no way to know what the original type of the data was, so the
+    /// same data type that was used for `create_timer` needs to be passed here to ensure
+    /// their types are identical.
+    pub fn stop_timer<T>(&self, timer_id: RedisModuleTimerID) -> Result<T, RedisError> {
+        let mut data: *mut c_void = std::ptr::null_mut();
+
+        let status: raw::Status =
+            unsafe { raw::RedisModule_StopTimer.unwrap()(self.ctx, timer_id, &mut data) }.into();
+
+        if status != raw::Status::Ok {
+            return Err(RedisError::Str(
+                "RedisModule_StopTimer failed, timer may not exist",
+            ));
+        }
+
+        let data: T = take_data(data);
+        return Ok(data);
+    }
+
+    /// Wrapper for `RedisModule_GetTimerInfo`.
+    ///
+    /// The caller is responsible for specifying the correct type for the returned data.
+    /// This function has no way to know what the original type of the data was, so the
+    /// same data type that was used for `create_timer` needs to be passed here to ensure
+    /// their types are identical.
+    pub fn get_timer_info<T>(
+        &self,
+        timer_id: RedisModuleTimerID,
+    ) -> Result<(Duration, &T), RedisError> {
+        let mut remaining: u64 = 0;
+        let mut data: *mut c_void = std::ptr::null_mut();
+
+        let status: raw::Status = unsafe {
+            raw::RedisModule_GetTimerInfo.unwrap()(self.ctx, timer_id, &mut remaining, &mut data)
+        }
+        .into();
+
+        if status != raw::Status::Ok {
+            return Err(RedisError::Str(
+                "RedisModule_GetTimerInfo failed, timer may not exist",
+            ));
+        }
+
+        // Cast the *mut c_void supplied by the Redis API to a raw pointer of our custom type.
+        let data = data as *mut T;
+
+        // Dereference the raw pointer (we know this is safe, since Redis should return our
+        // original pointer which we know to be good) and turn it into a safe reference
+        let data = unsafe { &*data };
+
+        Ok((Duration::from_millis(remaining), data))
+    }
+}
+
+fn take_data<T>(data: *mut c_void) -> T {
+    // Cast the *mut c_void supplied by the Redis API to a raw pointer of our custom type.
+    let data = data as *mut T;
+
+    // Take back ownership of the original boxed data, so we can unbox it safely.
+    // If we don't do this, the data's memory will be leaked.
+    let data = unsafe { Box::from_raw(data) };
+
+    *data
+}
+
+extern "C" fn raw_callback<F, T>(ctx: *mut raw::RedisModuleCtx, data: *mut c_void)
+where
+    F: FnOnce(&Context, T),
+{
+    let ctx = &Context::new(ctx);
+
+    if data.is_null() {
+        ctx.log_debug("[callback] Data is null; this should not happen!");
+        return;
+    }
+
+    let cb_data: CallbackData<F, T> = take_data(data);
+    (cb_data.callback)(ctx, cb_data.data);
+}