Class: Zizq::Crontab

Inherits:
Object
  • Object
show all
Defined in:
lib/zizq/crontab.rb,
sig/generated/zizq/crontab.rbs

Overview

Represents a Crontab schedule defined on the Zizq server.

This requires a Pro license on the Zizq server.

The actual data is lazily fetched when first accessed.

Crontabs are used to define collections of recurring jobs that run on a specified schedule, such as at 2am on every Monday. Each entry on the Crontab is a single job enqueue, which the Zizq server automatically triggers at the correct point in time. Zizq uses standard Cron expression syntax (with support for seconds via 6-fields) to define entries.

Entire schedules, and individual entries on a schedule, can be paused and resumed.

By default schedules operate in the system time zone of the Zizq server but an explicit IANA timezone name can be specified when defining the Crontab.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name) ⇒ Object

Initialize the Crontab with the given group name.

Parameters:

  • name (String) 


39
40
41
42
43
44
45
46
47
 
# File 'lib/zizq/crontab.rb', line 39

def initialize(name)
  @building = false #: bool
  @materialized = false #: bool
  @name = name #: String
  @entries = {} #: Hash[String, Zizq::CrontabEntry]
  @paused = false #: bool?
  @paused_at = nil #: Float?
  @resumed_at = nil #: Float?
end

Instance Attribute Details

#name ⇒ String (readonly)

The name of the cron group that this schedule is backed by.

Returns:

  • (String) 


28
29
30
 
# File 'lib/zizq/crontab.rb', line 28

def name
  @name
end

#paused ⇒ Object

Check if this schedule is currently paused.

Returns:

  • (Object) 


95
96
97
98
 
# File 'lib/zizq/crontab.rb', line 95

def paused #: () -> bool?
  materialize
  @paused
end

Instance Method Details

#clear ⇒ Object

Clear materialized data that was fetched from the Zizq server.

This triggers a refetch when the data is next accessed.

Returns:

  • (Object) 


64
65
66
67
68
69
70
71
72
 
# File 'lib/zizq/crontab.rb', line 64

def clear #: () -> self
  @entries = {}
  @paused = nil
  @paused_at = nil
  @resumed_at = nil
  @materialized = false

  self
end

#define_entry(name, expression, timezone: nil, paused: nil) ⇒ Zizq::CrontabEntryBuilder

Define (or redefine) an entry with this Crontab schedule.

Defining the same entry more than once is idempotent. If the entry does not exist, it is added to the schedule. If the entry already exists, it replaces the current entry.

The return value is a Zizq::CrontabEntryBuilder instance, on which the caller must call one of the enqueue methods (enqueue, enqueue_raw, optionally chained onto enqueue_with, exactly the same as a regular job enqueue).

All enqueue options are supported except delay and ready_at which make no sense for recurring jobs.

Bulk enqueues are not supported.

crontab.define_entry(
"refresh_data_warehose",
"*/15 * * * *",
).enqueue(RefreshDataWarehoseJob, incremental: true)

Parameters:

  • name (String)
  • expression (String)
  • timezone: (String, nil) (defaults to: nil)
  • paused: (Boolean, nil) (defaults to: nil)

Returns:



197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/zizq/crontab.rb', line 197

def define_entry(name, expression, timezone: nil, paused: nil)
  CrontabEntryBuilder.new(self, name, expression, timezone:, paused:) do |e|
    entry = materialize_entry_with(
      Zizq.client.replace_cron_group_entry(
        self.name,
        name,
        expression: e.expression,
        job: e.job.to_enqueue_params,
        timezone: e.timezone,
        paused: e.paused,
      ),
    )

    materialize # in case this was the first entry operation

    entry
  end
end

#delete! ⇒ Object

Delete this entire Crontab schedule and its entries.

Returns:

  • (Object) 


75
76
77
 
# File 'lib/zizq/crontab.rb', line 75

def delete! #: () -> void
  Zizq.client.delete_cron_group(name)
end

#entries ⇒ Object

Return a Hash of Zizq::CrontabEntry instances keyed by their names.

Each entry specifies the cron expression at which it executes, information about when it last/next enqueued a job, and details of the job that the entry enqueues.

Returns:

  • (Object) 


122
123
124
125
 
# File 'lib/zizq/crontab.rb', line 122

def entries #: () -> Hash[String, Zizq::CrontabEntry]
  materialize
  @entries
end

#entry(name) ⇒ Zizq::CrontabEntry

Return a handle for the specified Zizq::CrontabEntry.

The entry can be paused or resumed is isolation, can be deleted entirely or can be redefined (replaced) with another entry.

Parameters:

  • name (String)

Returns:



161
162
163
164
165
166
167
168
169
 
# File 'lib/zizq/crontab.rb', line 161

def entry(name)
  materialize
  entries.fetch(name) do
    entry = materialize_entry_with(
      Zizq.client.get_cron_group_entry(self.name, name),
    )
    entries[name] = entry
  end
end

#materialize ⇒ Object

Fetch data from the Zizq server if not already fetched.

Once fetched, this method becomes a no-op, unless #clear is called to remove the fetched data.

Returns:

  • (Object) 


53
54
55
56
57
58
59
 
# File 'lib/zizq/crontab.rb', line 53

def materialize #: () -> self
  unless @building || @materialized
    materialize_with(Zizq.client.get_cron_group(name))
  end

  self
end

#materialize_entry_with(result) ⇒ Zizq::CrontabEntry

Parameters:

Returns:



239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
 
# File 'lib/zizq/crontab.rb', line 239

def materialize_entry_with(result)
  CrontabEntry.new(
    self,
    result.name,
    result.expression,
    job: EnqueueRequest.new(
      type: result.job.type,
      queue: result.job.queue,
      priority: result.job.priority,
      payload: result.job.payload,
      retry_limit: result.job.retry_limit,
      backoff: result.job.backoff,
      retention: result.job.retention,
      unique_key: result.job.unique_key,
      unique_while: result.job.unique_while,
    ),
    paused: result.paused?,
    paused_at: result.paused_at,
    resumed_at: result.resumed_at,
    last_enqueue_at: result.last_enqueue_at,
    next_enqueue_at: result.next_enqueue_at,
  )
end

#materialize_with(result) ⇒ self

Parameters:

Returns:

  • (self) 


220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/zizq/crontab.rb', line 220

def materialize_with(result)
  @paused = result.paused?
  @paused_at = result.paused_at
  @resumed_at = result.resumed_at

  @entries = result.entries.map do |entry|
    [
      entry.name,
      materialize_entry_with(entry),
    ]
  end.to_h

  @materialized = true

  self
end

#pause! ⇒ Object

Pause this entire Crontab schedule.

All entries will stop enqueueing jobs, but the server continues to advance the schedule until it is resumed.

Returns:

  • (Object) 


83
84
85
 
# File 'lib/zizq/crontab.rb', line 83

def pause! #: () -> void
  materialize_with(Zizq.client.update_cron_group(name, paused: true))
end

#paused? ⇒ Object

Check if this schedule is currently paused.

Alias of #paused.

Returns:

  • (Object) 


103
 
# File 'lib/zizq/crontab.rb', line 103

def paused? = paused #: () -> bool?

#paused_at ⇒ Object

Return the timestamp at which this Crontab schedule was last paused.

Returns:

  • (Object) 


106
107
108
109
 
# File 'lib/zizq/crontab.rb', line 106

def paused_at #: () -> Float?
  materialize
  @paused_at
end

#redefine(timezone: nil, paused: nil) {|arg0| ... } ⇒ self

Redefine (replace) this Crontab schedule with another.

This is equivalent to calling Zizq.define_crontab and is idempotent when given the same schedule more than once.

Parameters:

  • timezone: (Object) (defaults to: nil)
  • paused: (Object) (defaults to: nil)

Yields:

Yield Parameters:

Yield Returns:

  • (void)

Returns:

  • (self) 


136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/zizq/crontab.rb', line 136

def redefine(timezone: nil, paused: nil, &block)
  @building = true

  yield CrontabBuilder.new(self, timezone:, paused:)

  materialize_with(
    Zizq.client.replace_cron_group(
      name,
      paused:,
      entries: entries.values.map(&:to_params),
    ),
  )

  @building = false

  self
end

#resume! ⇒ Object

Resume this Crontab schedule if it is currently paused.

Individual entries that are paused will remain paused.

Returns:

  • (Object) 


90
91
92
 
# File 'lib/zizq/crontab.rb', line 90

def resume! #: () -> void
  materialize_with(Zizq.client.update_cron_group(name, paused: false))
end

#resumed_at ⇒ Object

Return the timestamp at which this Crontab schedule was last resumed.

Returns:

  • (Object) 


112
113
114
115
 
# File 'lib/zizq/crontab.rb', line 112

def resumed_at #: () -> Float?
  materialize
  @resumed_at
end