<?php
namespace SabaiApps\Directories\Platform;

interface IScheduler {

	/**
	 * Initializes actions.
	 *
	 * @param array $actions An associative array of action names and their corresponding info arrays.
	 *                       Each info array may contain 'recurrence', 'args', 'priority', and 'timestamp' keys.
	 */
	public function initActions( array $actions );

	/**
	 * Schedules a recurring action.
	 *
	 * @param string   $recurrence How often the event should recur. Accepts 'hourly', 'twicedaily', 'daily', or a custom interval.
	 * @param string   $action The name of the action to be scheduled.
	 * @param array    $args Optional. An array of arguments to pass to the action hook's callback function.
	 * @param int      $priority Optional. The priority at which to execute the action hook's callback function. Default is 10.
	 * @param int|null $timestamp Optional. The time the first occurrence of the event is to be scheduled for, as a Unix timestamp. Default is current time.
	 * @return bool
	 */
	public function scheduleRecurringAction( $recurrence, $action, array $args = array(), $priority = 10, $timestamp = null );

	/**
	 * Schedules a single action.
	 *
	 * @param int    $timestamp The time the first occurrence of the event is to be scheduled for, as a Unix timestamp.
	 * @param string $action The name of the action to be scheduled.
	 * @param array  $args Optional. An array of arguments to pass to the action hook's callback function.
	 * @return bool
	 */
	public function scheduleSingleAction( $action, array $args = array(), $priority = 10, $timestamp = null );

	/**
	 * Enqueues an action to be run as soon as possible.
	 *
	 * @param string $action The name of the action to be scheduled.
	 * @param array  $args Optional. An array of arguments to pass to the action hook's callback function.
	 * @param int    $priority Optional. The priority at which to execute the action hook's callback function. Default is 10.
	 * @return bool
	 */
	public function enqueueAction( $action, array $args = array(), $priority = 10 );

	/**
	 * Gets the next scheduled occurrence of an action.
	 *
	 * @param string $action The name of the action to be checked.
	 * @param array  $args Optional. An array of arguments to pass to the action hook's callback function.
	 * @return int|false The timestamp of the next scheduled occurrence, or
	 */
	public function nextScheduledAction( $action, array $args = array() );

	/**
	 * Clears all scheduled occurrences of an action.
	 *
	 * @param string $action The name of the action to be cleared.
	 * @param array  $args Optional. An array of arguments to pass to the action hook
	 * @return bool
	 */
	public function clearScheduledAction( $action, $args = array() );
}
