Proposal: Introduce a new API to wait until a given scheduled job is completed

[kalaiyarasiganeshalingam]

Summary

In the task module, we can schedule the one-time or recursive job, but this scheduler does not wait until that scheduled job is finished. So we have to on-hold the execution by using runtime:sleep("TIME_IN_SECONDS");. So, this proposal introduces a new API to wait until that scheduled job is completed.

Goals

Provide a way to on-hold the execution until the scheduled task is completed.

Motivation

As mentioned in the summary, the user doesn't have a direct way to on-hold the execution until the scheduled task is completed. If a user scheduled the task with the runtime:sleep API, they have to calculate the time in seconds. So, this way is hard to schedule long-term jobs. It would be easy for them if we provided an API to handle it.

Description

# Schedule the given `task:Job` for the given time and wait until  that task is completed.
# ```ballerina
# time:Utc newTime = time:utcAddSeconds(time:utcNow(), 3);
# time:Civil time = time:utcToCivil(newTime);
# future<Error?> result = task:scheduleOneTimeJobAndWait(new Job(), time);
# ```
#
# + triggerTime - The specific time in Ballerina `time:Civil` to trigger only one time
# + job - Ballerina job, which is to be executed during the trigger
# + return - A `future<Error?>`
public isolated function scheduleOneTimeJobAndWait(Job job, time:Civil triggerTime) returns future<Error?>;

# Schedule the recurring `task:Job` according to the given duration and wait until  that task is completed.
# ```ballerina
# future<Error?> result = task:scheduleJobRecurByFrequency(new Job(), 3);
# ```
#
# + job - Ballerina job, which is to be executed by the scheduler
# + interval - The duration of the trigger (in seconds), which is used to run the job frequently
# + maxCount - The maximum number of trigger counts
# + startTime - The trigger start time in Ballerina `time:Civil`. If it is not provided, a trigger will
#               start immediately
# + endTime - The trigger end time in Ballerina `time:Civil`
# + taskPolicy -  The policy, which is used to handle the error and will be waiting during the trigger time
# + return - A `future<Error?>`
public isolated function scheduleJobRecurByFrequencyAndWait(Job job,  decimal interval,  int maxCount = -1,
                                    time:Civil? startTime = (), time:Civil? endTime = (), 
                                    TaskPolicy taskPolicy = {}) returns future<Error?>;