search

vapor / queues

A queue system for Vapor.
MIT License
169 stars 41 forks source link

`.every` functions adding the ability to run a job every `amount` in a given `interval` #97

Closed MahdiBM closed 3 years ago

MahdiBM commented 3 years ago

What does this PR add to the queues package?

This PR adds the ability to schedule a ScheduledJob to be run at different times in any interval. For example you can call the .every(_:in:) functions like so .every(.seconds(5), in: .minutes(1)) and expect the schedule to be run every 5 seconds in a minute, indefinitely.

Motivation

I've not only seen other people be looking for such option in a long time, but i myself have been looking forward to having such options as well. I also saw the open issue here on github, and saw tanner suggesting the syntax .every for a function which allows people do the same thing that i implemented. That led me to think about contributing to the package by implementing this feature myself.

What exactly is implemented?

How was this implementations made possible?

When we want to schedule a job, we need to do like so: app.queues.schedule(ScheduledJob()) which prior to this PR, would return a class ScheduleBuilder. We then can add time specifications to the builder using the available functions like .at(Date()) or .minutely().at(5). The first problem in the way of implementing .every functions is that a builder is supposed to only contain one job and one time, and the ScheduleBuilder neither can contain more than one time for a job, nor can produce more schedules of its own kind which have different times than itself. To fix this, i came up with 2-3 different ways, and chose the one that you see. I decided to make a change as described below:

What ScheduleContainer does is to hold multiple values of ScheduleContainer.Builder, plus the job that the builders are supposed to be scheduled with. So you'll see this in declaration of ScheduleContainer:

public let job: ScheduledJob
public var builders: [Builder] = []

public init(job: ScheduledJob) {
    self.job = job
}

I also changed Builder a little bit to hold a reference to its container, as well as using uuid to be able to identify builders that are in a container:

public let id = UUID()
public let container: ScheduleContainer

I also changed the way that a builder holds the time that it should be scheduled at, by introducing an enum:

public let id = UUID()
public let container: ScheduleContainer
private var _timeValue: TimeValue? = nil

TimeValue:

public enum TimeValue {
            case exact(date: Date)
            case intervalBased(offset: TimeInterval,
                               interval: TimeInterval,
                               isFirstLifecycle: Bool = true)
            case componentBased(month: Month? = nil,
                                day: Day? = nil,
                                weekday: Weekday? = nil,
                                time: Time? = nil,
                                minute: Minute? = nil,
                                second: Second? = nil,
                                nanosecond: Int? = nil)
}

Now a builder can clean-ly hold its time. This also helps when calculating the nextDate.

Another also, i declared convenience functions on top of ScheduleContainer which also avoids breaking people's codes. So as an example, the first function is in Builder, and the second one is in ScheduleContainer:

// MARK: - In `ScheduleContainer.Builder`:
/// Creates a monthly scheduled job for further building
    public func monthly() -> Monthly {
        return Monthly(builder: self)
    }

// MARK: - In `ScheduleContainer`
/// Creates a monthly scheduled job for further building
    public func monthly() -> Builder.Monthly {
        return Builder.Monthly(builder: Builder(container: self))
    }

One thing remaining, is that now that we have containers, one problem appears. The problem is that when we call app.queues.schedule(JOB()), the AnyScheduledJobs must not be immediately created. Instead, they should be created after the user is done with adding their builders to the container. If the app tries to create AnyScheduledJobs out of a container's job and builders immediately after the .schedule(_:) call happens, when it checks for builders, it'll see an empty array and basically no jobs will be added to the QueuesConfiguration. To tackle this i changed the scheduler to store all containers, and only calculate AnyScheduledJobs when needed:

// Previously:
var scheduledJobs: [AnyScheduledJob]

// Right now:
var scheduledJobsContainers: [ScheduleContainer]
var scheduledJobs: [AnyScheduledJob] {
    scheduledJobsContainers.map { container in
        container.builders.map { builder in
            AnyScheduledJob(job: container.job, scheduler: builder)
        }
    }.reduce(into: [AnyScheduledJob]()) { $0 += $1 }
}

This is the summary of what i've done. You can dig into the files more, and i've left some comments there as well. Feel free to ask any questions you might have, or point out any issues with this implementation.

My questions from those who check the code

These are basically the more-important things that i think i could improve:

MahdiBM commented 3 years ago

Going to #98