scheduler table doc update (#77)

Author: Shubham8287

docs/docs/modules/c-sharp/index.md

@@ -295,30 +295,77 @@ public static void PrintInfo(ReducerContext e)
 }
 ```
 
-`[SpacetimeDB.Reducer]` also generates a function to schedule the given reducer in the future.
 
-Since it's not possible to generate extension methods on existing methods, the codegen will instead add a `Schedule`-prefixed method colocated in the same namespace as the original method instead. The generated method will accept `DateTimeOffset` argument for the time when the reducer should be invoked, followed by all the arguments of the reducer itself, except those that have type `ReducerContext`.
+### Scheduler Tables
+Tables can be used to schedule a reducer calls either at a specific timestamp or at regular intervals.
 
 ```csharp
-// Example reducer:
-[SpacetimeDB.Reducer]
-public static void Add(string name, int age) { ... }
+public static partial class Timers
+{
+  
+    // The `Scheduled` attribute links this table to a reducer.
+    [SpacetimeDB.Table(Scheduled = nameof(SendScheduledMessage))]
+    public partial struct SendMessageTimer
+    {
+        public string Text;
+    }
 
-// Auto-generated by the codegen:
-public static void ScheduleAdd(DateTimeOffset time, string name, int age) { ... }
+     
+    // Define the reducer that will be invoked by the scheduler table.
+    // The first parameter is always `ReducerContext`, and the second parameter is an instance of the linked table struct.
+    [SpacetimeDB.Reducer]
+    public static void SendScheduledMessage(ReducerContext ctx, SendMessageTimer arg)
+    {
+        // ...
+    }
 
-// Usage from another reducer:
-[SpacetimeDB.Reducer]
-public static void AddIn5Minutes(ReducerContext e, string name, int age)
-{
-    // Note that we're using `e.Time` instead of `DateTimeOffset.Now` which is not allowed in modules.
-    var scheduleToken = ScheduleAdd(e.Time.AddMinutes(5), name, age);
 
-    // We can cancel the scheduled reducer by calling `Cancel()` on the returned token.
-    scheduleToken.Cancel();
+    // Scheduling reducers inside `init` reducer.
+    [SpacetimeDB.Reducer(ReducerKind.Init)]
+    public static void Init(ReducerContext ctx)
+    {
+
+        // Schedule a one-time reducer call by inserting a row.
+        new SendMessageTimer
+        {
+            Text = "bot sending a message",
+            ScheduledAt = ctx.Time.AddSeconds(10),
+            ScheduledId = 1,
+        }.Insert();
+
+
+        // Schedule a recurring reducer.
+        new SendMessageTimer
+        {
+            Text = "bot sending a message",
+            ScheduledAt = new TimeStamp(10),
+            ScheduledId = 2,
+        }.Insert();
+    }
 }
 ```
 
+Annotating a struct with `Scheduled` automatically adds fields to support scheduling, It can be expanded as:
+
+```csharp
+public static partial class Timers
+{
+    [SpacetimeDB.Table]
+    public partial struct SendMessageTimer
+    {
+        public string Text;         // fields of original struct
+       
+        [SpacetimeDB.Column(ColumnAttrs.PrimaryKeyAuto)]
+        public ulong ScheduledId;   // unique identifier to be used internally
+        
+        public SpacetimeDB.ScheduleAt ScheduleAt;   // Scheduling details (Time or Inteval)
+    }
+}
+
+// `ScheduledAt` definition
+public abstract partial record ScheduleAt: SpacetimeDB.TaggedEnum<(DateTimeOffset Time, TimeSpan Interval)>
+```
+
 #### Special reducers
 
 These are four special kinds of reducers that can be used to respond to module lifecycle events. They're stored in the `SpacetimeDB.Module.ReducerKind` class and can be used as an argument to the `[SpacetimeDB.Reducer]` attribute:

docs/docs/modules/rust/index.md

@@ -167,8 +167,6 @@ struct Person {
 
 ### Defining reducers
 
-`#[spacetimedb(reducer)]` optionally takes a single argument, which is a frequency at which the reducer will be automatically called by the database.
-
 `#[spacetimedb(reducer)]` is always applied to top level Rust functions. They can take arguments of types known to SpacetimeDB (just like fields of structs must be known to SpacetimeDB), and either return nothing, or return a `Result<(), E: Debug>`.
 
 ```rust
@@ -192,39 +190,75 @@ struct Item {
 
 Note that reducers can call non-reducer functions, including standard library functions.
 
-Reducers that are called periodically take an additional macro argument specifying the frequency at which they will be invoked. Durations are parsed according to https://docs.rs/humantime/latest/humantime/fn.parse_duration.html and will usually be a number of milliseconds or seconds.
 
-Both of these examples are invoked every second.
+There are several macros which modify the semantics of a column, which are applied to the members of the table struct. `#[unique]` and `#[autoinc]` are covered below, describing how those attributes affect the semantics of inserting, filtering, and so on.
 
-```rust
-#[spacetimedb(reducer, repeat = 1s)]
-fn every_second() {}
+#[SpacetimeType]
 
-#[spacetimedb(reducer, repeat = 1000ms)]
-fn every_thousand_milliseconds() {}
-```
+#[sats]
 
-Finally, reducers can also receive a ReducerContext object, or the Timestamp at which they are invoked, just by taking parameters of those types first.
+### Defining Scheduler Tables
+Tables can be used to schedule a reducer calls either at a specific timestamp or at regular intervals.
 
 ```rust
-#[spacetimedb(reducer, repeat = 1s)]
-fn tick_timestamp(time: Timestamp) {
-    println!("tick at {time}");
+// The `scheduled` attribute links this table to a reducer.
+#[spacetimedb(table, scheduled(send_message))]
+struct SendMessageTimer {
+    text: String,
 }
+```
 
-#[spacetimedb(reducer, repeat = 500ms)]
-fn tick_ctx(ctx: ReducerContext) {
-    println!("tick at {}", ctx.timestamp)
+The `scheduled` attribute adds a couple of default fields and expands as follows: 
+```rust
+#[spacetimedb(table)]
+ struct SendMessageTimer {
+    text: String,   // original field
+    #[primary]
+    #[autoinc]
+    scheduled_id: u64, // identifier for internal purpose
+    scheduled_at: ScheduleAt, //schedule details
+}
+
+pub enum ScheduleAt {
+    /// A specific time at which the reducer is scheduled.
+    /// Value is a UNIX timestamp in microseconds.
+    Time(u64),
+    /// A regular interval at which the repeated reducer is scheduled.
+    /// Value is a duration in microseconds.
+    Interval(u64),
 }
 ```
 
-Note that each distinct time a repeating reducer is invoked, a seperate schedule is created for that reducer. So invoking `every_second` three times from the spacetimedb cli will result in the reducer being called times times each second.
+Managing timers with scheduled table is as simple as inserting or deleting rows from table.
+```rust
+#[spacetimedb(reducer)]
 
-There are several macros which modify the semantics of a column, which are applied to the members of the table struct. `#[unique]` and `#[autoinc]` are covered below, describing how those attributes affect the semantics of inserting, filtering, and so on.
+// Reducers linked to the scheduler table should have their first argument as `ReducerContext` 
+// and the second as an instance of the table struct it is linked to.
+fn send_message(ctx: ReducerContext, arg: SendMessageTimer) -> Result<(), String> {
+    // ...
+}
 
-#[SpacetimeType]
+// Scheduling reducers inside `init` reducer
+fn init() {
+    // Scheduling a reducer for a specific Timestamp
+    SendMessageTimer::insert(SendMessageTimer {
+        scheduled_id: 1,
+        text:"bot sending a message".to_string(),
+        //`spacetimedb::Timestamp` implements `From` trait to `ScheduleAt::Time`. 
+        scheduled_at: ctx.timestamp.plus(Duration::from_secs(10)).into()
+    });
+
+    // Scheduling a reducer to be called at fixed interval of 100 milliseconds.
+    SendMessageTimer::insert(SendMessageTimer {
+        scheduled_id: 0,
+        text:"bot sending a message".to_string(),
+        //`std::time::Duration` implements `From` trait to `ScheduleAt::Duration`. 
+        scheduled_at: duration!(100ms).into(),
+    });
+}
+```
 
-#[sats]
 
 ## Client API
 

docs/docs/unity/part-4.md

@@ -98,11 +98,16 @@ pub struct Config {
 
 ### Step 2: Write our Resource Spawner Repeating Reducer
 
-1. Add the following code to lib.rs. We are using a special attribute argument called repeat which will automatically schedule the reducer to run every 1000ms.
+1. Add the following code to lib.rs. As we want to schedule `resource_spawn_agent` to run later, It will require to implement a scheduler table.
 
 ```rust
-#[spacetimedb(reducer, repeat = 1000ms)]
-pub fn resource_spawner_agent(_ctx: ReducerContext, _prev_time: Timestamp) -> Result<(), String> {
+#[spacetimedb(table, scheduled(resource_spawner_agent))]
+struct ResouceSpawnAgentSchedueler {
+    _prev_time: Timestamp,
+}
+
+#[spacetimedb(reducer)
+pub fn resource_spawner_agent(_ctx: ReducerContext, _arg: ResourceSpawnAgentScheduler) -> Result<(), String> {
     let config = Config::find_by_version(&0).unwrap();
 
     // Retrieve the maximum number of nodes we want to spawn from the Config table
@@ -157,18 +162,24 @@ pub fn resource_spawner_agent(_ctx: ReducerContext, _prev_time: Timestamp) -> Re
 }
 ```
 
+
 2. Since this reducer uses `rand::Rng` we need add include it. Add this `use` statement to the top of lib.rs.
 
 ```rust
 use rand::Rng;
 ```
 
-3. Even though our reducer is set to repeat, we still need to schedule it the first time. Add the following code to the end of the `init` reducer. You can use this `schedule!` macro to schedule any reducer to run in the future after a certain amount of time.
+3. Add the following code to the end of the `init` reducer to set the reducer to repeat at every regular interval.
 
 ```rust
     // Start our resource spawner repeating reducer
-    spacetimedb::schedule!("1000ms", resource_spawner_agent(_, Timestamp::now()));
+    ResouceSpawnAgentSchedueler::insert(ResouceSpawnAgentSchedueler {
+        _prev_time: TimeStamp::now(),
+        scheduled_id: 1,
+        scheduled_at: duration!(1000ms).into()
+    }).expect();
 ```
+struct ResouceSpawnAgentSchedueler {
 
 4. Next we need to generate our client code and publish the module. Since we changed the schema we need to make sure we include the `--clear-database` flag. Run the following commands from your Server directory: