MDL-51360 core_grades: Improve documentation of grade_get_grades().

[moodle.git] / lib / classes / cron.php

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

namespace core;

use coding_exception;
use core_php_time_limit;
use moodle_exception;
use stdClass;

// Disable the moodle.PHP.ForbiddenFunctions.FoundWithAlternative sniff for this file.
// It detects uses of error_log() which are valid in this file.
// phpcs:disable moodle.PHP.ForbiddenFunctions.FoundWithAlternative

/**
 * Cron and adhoc task functionality.
 *
 * @package    core
 * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class cron {

    /** @var ?stdClass A copy of the standard cron 'user' */
    protected static ?stdClass $cronuser = null;

    /** @var ?stdClass The cron user's session data */
    protected static ?stdClass $cronsession = null;

    /**
     * Use a default value of 3 minutes.
     * The recommended cron frequency is every minute, and the default adhoc concurrency is 3.
     * A default value of 3 minutes allows all adhoc tasks to be run concurrently at their default value.
     *
     * @var int The default keepalive value for the main cron runner
     */
    public const DEFAULT_MAIN_PROCESS_KEEPALIVE = 3 * MINSECS;

    /**
     * @var int The max keepalive value for the main cron runner
     */
    public const MAX_MAIN_PROCESS_KEEPALIVE = 15 * MINSECS;

    /**
     * Execute cron tasks
     *
     * @param int|null $keepalive The keepalive time for this cron run.
     */
    public static function run_main_process(?int $keepalive = null): void {
        global $CFG, $DB;

        if (CLI_MAINTENANCE) {
            echo "CLI maintenance mode active, cron execution suspended.\n";
            exit(1);
        }

        if (moodle_needs_upgrading()) {
            echo "Moodle upgrade pending, cron execution suspended.\n";
            exit(1);
        }

        require_once($CFG->libdir . '/adminlib.php');

        if (!empty($CFG->showcronsql)) {
            $DB->set_debug(true);
        }
        if (!empty($CFG->showcrondebugging)) {
            set_debugging(DEBUG_DEVELOPER, true);
        }

        core_php_time_limit::raise();

        // Increase memory limit.
        raise_memory_limit(MEMORY_EXTRA);

        // Emulate normal session. - we use admin account by default.
        self::setup_user();

        // Start output log.
        $timenow = time();
        mtrace("Server Time: " . date('r', $timenow) . "\n\n");

        // Record start time and interval between the last cron runs.
        $laststart = get_config('tool_task', 'lastcronstart');
        set_config('lastcronstart', $timenow, 'tool_task');
        if ($laststart) {
            // Record the interval between last two runs (always store at least 1 second).
            set_config('lastcroninterval', max(1, $timenow - $laststart), 'tool_task');
        }

        // Determine the time when the cron should finish.
        if ($keepalive === null) {
            $keepalive = get_config('core', 'cron_keepalive');
            if ($keepalive === false) {
                $keepalive = self::DEFAULT_MAIN_PROCESS_KEEPALIVE;
            }
        }

        if ($keepalive > self::MAX_MAIN_PROCESS_KEEPALIVE) {
            // Attempt to prevent abnormally long keepalives.
            mtrace("Cron keepalive time is too long, reducing to 15 minutes.");
            $keepalive = self::MAX_MAIN_PROCESS_KEEPALIVE;
        }

        // Calculate the finish time based on the start time and keepalive.
        $finishtime = $timenow + $keepalive;

        do {
            $startruntime = microtime();

            // Run all scheduled tasks.
            self::run_scheduled_tasks(time(), $timenow);

            // Run adhoc tasks.
            self::run_adhoc_tasks(time(), 0, true, $timenow);

            mtrace("Cron run completed correctly");

            gc_collect_cycles();

            $completiontime = date('H:i:s');
            $difftime = microtime_diff($startruntime, microtime());
            $memoryused = display_size(memory_get_usage());

            $message = "Cron completed at {$completiontime} in {$difftime} seconds. Memory used: {$memoryused}.";

            // Check if we should continue to run.
            // Only continue to run if:
            // - The finish time has not been reached; and
            // - The graceful exit flag has not been set; and
            // - The static caches have not been cleared since the start of the cron run.
            $remaining = $finishtime - time();
            $runagain = $remaining > 0;
            $runagain = $runagain && !\core\local\cli\shutdown::should_gracefully_exit();
            $runagain = $runagain && !\core\task\manager::static_caches_cleared_since($timenow);

            if ($runagain) {
                $message .= " Continuing to check for tasks for {$remaining} more seconds.";
                mtrace($message);
                sleep(1);

                // Re-check the graceful exit and cache clear flags after sleeping as these may have changed.
                $runagain = $runagain && !\core\local\cli\shutdown::should_gracefully_exit();
                $runagain = $runagain && !\core\task\manager::static_caches_cleared_since($timenow);
            } else {
                mtrace($message);
            }
        } while ($runagain);
    }

    /**
     * Execute all queued scheduled tasks, applying necessary concurrency limits and time limits.
     *
     * @param   int       $startruntime The time this run started.
     * @param   null|int  $startprocesstime The time the process that owns this runner started.
     * @throws \moodle_exception
     */
    public static function run_scheduled_tasks(
        int $startruntime,
        ?int $startprocesstime = null,
    ): void {
        // Allow a restriction on the number of scheduled task runners at once.
        $cronlockfactory = \core\lock\lock_config::get_lock_factory('cron');
        $maxruns = get_config('core', 'task_scheduled_concurrency_limit');
        $maxruntime = get_config('core', 'task_scheduled_max_runtime');

        if ($startprocesstime === null) {
            $startprocesstime = $startruntime;
        }

        $scheduledlock = null;
        for ($run = 0; $run < $maxruns; $run++) {
            // If we can't get a lock instantly it means runner N is already running
            // so fail as fast as possible and try N+1 so we don't limit the speed at
            // which we bring new runners into the pool.
            if ($scheduledlock = $cronlockfactory->get_lock("scheduled_task_runner_{$run}", 0)) {
                break;
            }
        }

        if (!$scheduledlock) {
            mtrace("Skipping processing of scheduled tasks. Concurrency limit reached.");
            return;
        }

        $starttime = time();

        // Run all scheduled tasks.
        try {
            while (
                !\core\local\cli\shutdown::should_gracefully_exit() &&
                !\core\task\manager::static_caches_cleared_since($startprocesstime) &&
                $task = \core\task\manager::get_next_scheduled_task($startruntime)
            ) {
                self::run_inner_scheduled_task($task);
                unset($task);

                if ((time() - $starttime) > $maxruntime) {
                    mtrace("Stopping processing of scheduled tasks as time limit has been reached.");
                    break;
                }
            }
        } finally {
            // Release the scheduled task runner lock.
            $scheduledlock->release();
        }
    }

    /**
     * Execute all queued adhoc tasks, applying necessary concurrency limits and time limits.
     *
     * @param   int     $startruntime The time this run started.
     * @param   int     $keepalive Keep this public static function alive for N seconds and poll for new adhoc tasks.
     * @param   bool    $checklimits Should we check limits?
     * @param   null|int $startprocesstime The time this process started.
     * @param   int|null $maxtasks Limit number of tasks to run`
     * @param   null|string $classname Run only tasks of this class
     * @throws \moodle_exception
     */
    public static function run_adhoc_tasks(
        int $startruntime,
        $keepalive = 0,
        $checklimits = true,
        ?int $startprocesstime = null,
        ?int $maxtasks = null,
        ?string $classname = null,
    ): void {
        // Allow a restriction on the number of adhoc task runners at once.
        $cronlockfactory = \core\lock\lock_config::get_lock_factory('cron');
        $maxruns = get_config('core', 'task_adhoc_concurrency_limit');
        $maxruntime = get_config('core', 'task_adhoc_max_runtime');

        if ($startprocesstime === null) {
            $startprocesstime = $startruntime;
        }

        $adhoclock = null;
        if ($checklimits) {
            for ($run = 0; $run < $maxruns; $run++) {
                // If we can't get a lock instantly it means runner N is already running
                // so fail as fast as possible and try N+1 so we don't limit the speed at
                // which we bring new runners into the pool.
                if ($adhoclock = $cronlockfactory->get_lock("adhoc_task_runner_{$run}", 0)) {
                    break;
                }
            }

            if (!$adhoclock) {
                mtrace("Skipping processing of adhoc tasks. Concurrency limit reached.");
                return;
            }
        }

        $humantimenow = date('r', $startruntime);
        $finishtime = $startruntime + $keepalive;
        $waiting = false;
        $taskcount = 0;

        // Run all adhoc tasks.
        while (
            !\core\local\cli\shutdown::should_gracefully_exit() &&
            !\core\task\manager::static_caches_cleared_since($startprocesstime)
        ) {

            if ($checklimits && (time() - $startruntime) >= $maxruntime) {
                if ($waiting) {
                    $waiting = false;
                    mtrace('');
                }
                mtrace("Stopping processing of adhoc tasks as time limit has been reached.");
                break;
            }

            try {
                $task = \core\task\manager::get_next_adhoc_task(time(), $checklimits, $classname);
            } catch (\Throwable $e) {
                if ($adhoclock) {
                    // Release the adhoc task runner lock.
                    $adhoclock->release();
                }
                throw $e;
            }

            if ($task) {
                if ($waiting) {
                    mtrace('');
                }
                $waiting = false;
                self::run_inner_adhoc_task($task);
                self::set_process_title("Waiting for next adhoc task");
                $taskcount++;
                if ($maxtasks && $taskcount >= $maxtasks) {
                    break;
                }
                unset($task);
            } else {
                $timeleft = $finishtime - time();
                if ($timeleft <= 0) {
                    break;
                }
                if (!$waiting) {
                    mtrace('Waiting for more adhoc tasks to be queued ', '');
                } else {
                    mtrace('.', '');
                }
                $waiting = true;
                self::set_process_title("Waiting {$timeleft}s for next adhoc task");
                sleep(1);
            }
        }

        if ($waiting) {
            mtrace('');
        }

        mtrace("Ran {$taskcount} adhoc tasks found at {$humantimenow}");

        if ($adhoclock) {
            // Release the adhoc task runner lock.
            $adhoclock->release();
        }
    }

    /**
     * Execute an adhoc task.
     *
     * @param   int       $taskid
     */
    public static function run_adhoc_task(int $taskid): void {
        $task = \core\task\manager::get_adhoc_task($taskid);
        if (!$task->get_fail_delay() && $task->get_next_run_time() > time()) {
            throw new \moodle_exception('wontrunfuturescheduledtask');
        }

        self::run_inner_adhoc_task($task);
        self::set_process_title("Running adhoc task $taskid");
    }

    /**
     * Execute all failed adhoc tasks.
     *
     * @param string|null  $classname Run only tasks of this class
     */
    public static function run_failed_adhoc_tasks(?string $classname = null): void {
        global $DB;

        $where = 'faildelay > 0';
        $params = [];
        if ($classname) {
            $where .= ' AND classname = :classname';
            $params['classname'] = \core\task\manager::get_canonical_class_name($classname);
        }

        // Only rerun the failed tasks that allow to be re-tried or have the remaining attempts available.
        $where .= ' AND (attemptsavailable > 0 OR attemptsavailable IS NULL)';
        $tasks = $DB->get_records_sql("SELECT * from {task_adhoc} WHERE $where", $params);
        foreach ($tasks as $t) {
            self::run_adhoc_task($t->id);
        }
    }

    /**
     * Shared code that handles running of a single scheduled task within the cron.
     *
     * Not intended for calling directly outside of this library!
     *
     * @param \core\task\task_base $task
     */
    public static function run_inner_scheduled_task(\core\task\task_base $task) {
        global $CFG, $DB;
        $debuglevel = $CFG->debug;
        $debugdisplay = $CFG->debugdisplay;
        $CFG->debugdisplay = 1;

        \core\task\manager::scheduled_task_starting($task);
        \core\task\logmanager::start_logging($task);

        $fullname = $task->get_name() . ' (' . get_class($task) . ')';
        mtrace('Execute scheduled task: ' . $fullname);
        self::set_process_title('Scheduled task: ' . get_class($task));
        self::trace_time_and_memory();
        $predbqueries = null;
        $predbqueries = $DB->perf_get_queries();
        $pretime = microtime(1);

        // Ensure that we have a clean session with the correct cron user.
        self::setup_user();

        try {
            get_mailer('buffer');
            self::prepare_core_renderer();
            // Temporarily increase debug level if task has failed and debugging isn't already at maximum.
            if ($debuglevel !== DEBUG_DEVELOPER && $faildelay = $task->get_fail_delay()) {
                mtrace('Debugging increased temporarily due to faildelay of ' . $faildelay);
                set_debugging(DEBUG_DEVELOPER, 1);
            }
            $task->execute();
            if ($DB->is_transaction_started()) {
                throw new coding_exception("Task left transaction open");
            }
            if (isset($predbqueries)) {
                mtrace("... used " . ($DB->perf_get_queries() - $predbqueries) . " dbqueries");
                mtrace("... used " . (microtime(1) - $pretime) . " seconds");
            }
            mtrace('Scheduled task complete: ' . $fullname);
            \core\task\manager::scheduled_task_complete($task);
        } catch (\Throwable $e) {
            if ($DB && $DB->is_transaction_started()) {
                error_log('Database transaction aborted automatically in ' . get_class($task));
                $DB->force_transaction_rollback();
            }
            if (isset($predbqueries)) {
                mtrace("... used " . ($DB->perf_get_queries() - $predbqueries) . " dbqueries");
                mtrace("... used " . (microtime(1) - $pretime) . " seconds");
            }
            mtrace('Scheduled task failed: ' . $fullname . ',' . $e->getMessage());
            if ($CFG->debugdeveloper) {
                if (!empty($e->debuginfo)) {
                    mtrace("Debug info:");
                    mtrace($e->debuginfo);
                }
                mtrace("Backtrace:");
                mtrace(format_backtrace($e->getTrace(), true));
            }
            \core\task\manager::scheduled_task_failed($task);
        } finally {
            // Reset debugging if it changed.
            if ($CFG->debug !== $debuglevel) {
                set_debugging($debuglevel);
            }

            // Reset debugdisplay back.
            $CFG->debugdisplay = $debugdisplay;

            // Reset back to the standard admin user.
            self::setup_user();
            self::set_process_title('Waiting for next scheduled task');
            self::prepare_core_renderer(true);
        }
        get_mailer('close');
    }

    /**
     * Shared code that handles running of a single adhoc task within the cron.
     *
     * @param \core\task\adhoc_task $task
     */
    public static function run_inner_adhoc_task(\core\task\adhoc_task $task) {
        global $CFG, $DB;
        $debuglevel = $CFG->debug;
        $debugdisplay = $CFG->debugdisplay;
        $CFG->debugdisplay = 1;

        \core\task\manager::adhoc_task_starting($task);
        \core\task\logmanager::start_logging($task);

        mtrace("Execute adhoc task: " . get_class($task));
        mtrace("Adhoc task id: " . $task->get_id());
        mtrace("Adhoc task custom data: " . $task->get_custom_data_as_string());
        self::set_process_title('Adhoc task: ' . $task->get_id() . ' ' . get_class($task));
        self::trace_time_and_memory();
        $predbqueries = null;
        $predbqueries = $DB->perf_get_queries();
        $pretime = microtime(1);

        if ($userid = $task->get_userid()) {
            // This task has a userid specified.
            if ($user = \core_user::get_user($userid)) {
                // User found. Check that they are suitable.
                try {
                    \core_user::require_active_user($user, true, true);
                } catch (moodle_exception $e) {
                    mtrace("User {$userid} cannot be used to run an adhoc task: " . get_class($task) . ". Cancelling task.");
                    $user = null;
                }
            } else {
                // Unable to find the user for this task.
                // A user missing in the database will never reappear.
                mtrace("User {$userid} could not be found for adhoc task: " . get_class($task) . ". Cancelling task.");
            }

            if (empty($user)) {
                // A user missing in the database will never reappear so the task needs to be failed to ensure that locks are
                // removed, and then removed to prevent future runs.
                // A task running as a user should only be run as that user.
                \core\task\manager::adhoc_task_failed($task);
                $DB->delete_records('task_adhoc', ['id' => $task->get_id()]);

                return;
            }

            self::setup_user($user);
        } else {
            // No user specified, ensure that we have a clean session with the correct cron user.
            self::setup_user();
        }

        try {
            get_mailer('buffer');
            self::prepare_core_renderer();
            // Temporarily increase debug level if task has failed and debugging isn't already at maximum.
            if ($debuglevel !== DEBUG_DEVELOPER && $faildelay = $task->get_fail_delay()) {
                mtrace('Debugging increased temporarily due to faildelay of ' . $faildelay);
                set_debugging(DEBUG_DEVELOPER, 1);
            }
            $task->execute();
            if ($DB->is_transaction_started()) {
                throw new coding_exception("Task left transaction open");
            }
            if (isset($predbqueries)) {
                mtrace("... used " . ($DB->perf_get_queries() - $predbqueries) . " dbqueries");
                mtrace("... used " . (microtime(1) - $pretime) . " seconds");
            }
            mtrace("Adhoc task complete: " . get_class($task));
            \core\task\manager::adhoc_task_complete($task);
        } catch (\Throwable $e) {
            if ($DB && $DB->is_transaction_started()) {
                error_log('Database transaction aborted automatically in ' . get_class($task));
                $DB->force_transaction_rollback();
            }
            if (isset($predbqueries)) {
                mtrace("... used " . ($DB->perf_get_queries() - $predbqueries) . " dbqueries");
                mtrace("... used " . (microtime(1) - $pretime) . " seconds");
            }
            mtrace("Adhoc task failed: " . get_class($task) . "," . $e->getMessage());
            if ($CFG->debugdeveloper) {
                if (!empty($e->debuginfo)) {
                    mtrace("Debug info:");
                    mtrace($e->debuginfo);
                }
                mtrace("Backtrace:");
                mtrace(format_backtrace($e->getTrace(), true));
            }
            \core\task\manager::adhoc_task_failed($task);
        } finally {
            // Reset debug level if it changed.
            if ($CFG->debug !== $debuglevel) {
                set_debugging($debuglevel);
            }

            // Reset debugdisplay back.
            $CFG->debugdisplay = $debugdisplay;

            // Reset back to the standard admin user.
            self::setup_user();
            self::prepare_core_renderer(true);
        }
        get_mailer('close');
    }

    /**
     * Sets the process title
     *
     * This makes it very easy for a sysadmin to immediately see what task
     * a cron process is running at any given moment.
     *
     * @param string $title process status title
     */
    public static function set_process_title(string $title) {
        global $CFG;
        if (CLI_SCRIPT) {
            require_once($CFG->libdir . '/clilib.php');
            $datetime = userdate(time(), '%b %d, %H:%M:%S');
            cli_set_process_title_suffix("$datetime $title");
        }
    }

    /**
     * Output some standard information during cron runs. Specifically current time
     * and memory usage. This method also does gc_collect_cycles() (before displaying
     * memory usage) to try to help PHP manage memory better.
     */
    public static function trace_time_and_memory() {
        gc_collect_cycles();
        mtrace('... started ' . date('H:i:s') . '. Current memory use ' . display_size(memory_get_usage()) . '.');
    }

    /**
     * Prepare the output renderer for the cron run.
     *
     * This involves creating a new $PAGE, and $OUTPUT fresh for each task and prevents any one task from influencing
     * any other.
     *
     * @param   bool    $restore Whether to restore the original PAGE and OUTPUT
     */
    public static function prepare_core_renderer($restore = false) {
        global $OUTPUT, $PAGE;

        // Store the original PAGE and OUTPUT values so that they can be reset at a later point to the original.
        // This should not normally be required, but may be used in places such as the scheduled task tool's "Run now"
        // functionality.
        static $page = null;
        static $output = null;

        if (null === $page) {
            $page = $PAGE;
        }

        if (null === $output) {
            $output = $OUTPUT;
        }

        if (!empty($restore)) {
            $PAGE = $page;
            $page = null;

            $OUTPUT = $output;
            $output = null;
        } else {
            // Setup a new General renderer.
            // Cron tasks may produce output to be used in web, so we must use the appropriate renderer target.
            // This allows correct use of templates, etc.
            $PAGE = new \moodle_page();
            $OUTPUT = new \core_renderer($PAGE, RENDERER_TARGET_GENERAL);
        }
    }

    /**
     * Sets up a user and course environment in cron.
     *
     * Note: This function is intended only for use in:
     * - the cron runner scripts
     * - individual tasks which extend the adhoc_task and scheduled_task classes
     * - unit tests related to tasks
     * - other parts of the cron/task system
     *
     * Please note that this function stores cache data statically.
     * @see reset_user_cache() to reset this cache.
     *
     * @param null|stdClass $user full user object, null means default cron user (admin)
     * @param null|stdClass $course full course record, null means $SITE
     * @param null|bool $leavepagealone If specified, stops it messing with global page object
     */
    public static function setup_user(?stdClass $user = null, ?stdClass $course = null, bool $leavepagealone = false): void {
        // This function uses the $GLOBALS super global. Disable the VariableNameLowerCase sniff for this function.
        // phpcs:disable moodle.NamingConventions.ValidVariableName.VariableNameLowerCase
        global $CFG, $SITE, $PAGE;

        if (!CLI_SCRIPT && !$leavepagealone) {
            throw new coding_exception('It is not possible to use \core\cron\setup_user() in normal requests!');
        }

        if (empty(self::$cronuser)) {
            // The cron user is essentially the admin user, but with some value removed.
            // We ginore the timezone language, and locale preferences - use the site default instead.
            self::$cronuser = get_admin();
            self::$cronuser->timezone = $CFG->timezone;
            self::$cronuser->lang = '';
            self::$cronuser->theme = '';
            unset(self::$cronuser->description);

            self::$cronsession = new stdClass();
        }

        if (!$user) {
            // Cached default cron user (==modified admin for now).
            \core\session\manager::init_empty_session();
            \core\session\manager::set_user(self::$cronuser);
            $GLOBALS['SESSION'] = self::$cronsession;
        } else {
            // Emulate real user session - needed for caps in cron.
            if ($GLOBALS['USER']->id != $user->id) {
                \core\session\manager::init_empty_session();
                \core\session\manager::set_user($user);
            }
        }

        // TODO MDL-19774 relying on global $PAGE in cron is a bad idea.
        // Temporary hack so that cron does not give fatal errors.
        if (!$leavepagealone) {
            $PAGE = new \moodle_page();
            $PAGE->set_course($course ?? $SITE);
        }

        // TODO: it should be possible to improve perf by caching some limited number of users here.
        // phpcs:enable
    }

    /**
     * Resets the cache for the cron user used by `setup_user()`.
     */
    public static function reset_user_cache(): void {
        self::$cronuser = null;
        self::$cronsession = null;
        \core\session\manager::init_empty_session();
    }
}