Background tasks

Anything that can take longer than a few seconds does not run while you wait for a page: it runs in the background, in small batches, so a big job never times out and never blocks the site. The engine is Action Scheduler, which ships with the plugin and is also used by WooCommerce and many other plugins. All of this plugin's jobs use the Action Scheduler group wpmcf.

There are two kinds of background work:

The free plugin has no separate Tasks screen: a task is always shown by the feature that owns it, and you can list tasks from the command line (wp wpmcf tasks list).

How a run works

1. You start the job (or its schedule fires). The plugin queues an Action Scheduler action.
2. WordPress runs the action. Each batch works until its budget is spent: about 20 seconds or 80 % of the PHP memory limit, whichever comes first.
3. If work remains, the next batch is queued at once. The batches continue until the run finishes.
4. When the run finishes the task becomes Completed, or, for a recurring task, waits for its next run (never sooner than one minute).

Each batch continues exactly where the last stopped, so a crash or restart never repeats finished work.

What starts the queue. When you press a button in the admin, the plugin asks Action Scheduler to start right after the request. Otherwise batches are picked up by WP-Cron, roughly every minute while the site gets visits. On sites with little traffic or with WP-Cron disabled, run the queue from a system cron job (see WP-CLI):

wp action-scheduler run --group=wpmcf

Task statuses

Each run also leaves a log entry with the status Processing, Completed or Failed, a message, and the finish time. The last 20 logs of a task are kept.

Failures and retries

A batch that throws an error is not lost:

The delay doubles with each attempt up to one hour. A successful batch resets the counter to zero.

To fix a failed task, remove the cause (the message says what failed), then activate the task again from the feature screen or run it with wp wpmcf tasks run <id>.

Locks and the watchdog

• Only one batch of a task runs at a time. A running batch holds a lock for up to 10 minutes.
• If a batch is cut off (a PHP fatal error, a timeout or running out of memory), no follow-up is queued. A watchdog that runs every 15 minutes finds active tasks with no queued action whose last batch is older than 15 minutes, and queues them again.
• When the plugin is deactivated and activated again, active tasks are queued again automatically.

Pause, reset and delete

If the module that owns a task is gone (for example the Pro code was removed), the task is kept but paused, so nothing fails at random. It starts again when the code is back and you activate it.

The ACF migration

The ACF migration does not use the task table. It is one job with its own status:

It handles 50 objects per batch inside the same time and memory budget. A batch holds a 10-minute lock. If nothing is queued and nothing moved for five minutes, Resume appears. Details are in Migrating from ACF.

Where to look when something is stuck

1. The feature screen (Programmatic SEO, Data tables or Tools › Migrate from ACF): status, last run message and the last error.
2. Tools › Scheduled Actions in WordPress (Action Scheduler's own list). Filter by the group wpmcf and the status Pending, In-progress, Failed. Pending actions with a past date mean the queue is not running: see What starts the queue.
3. WPM Fields › Settings › Health: errors caught while a job ran. See Health and troubleshooting.
4. wp wpmcf tasks list shows status, next_run and attempts for every task.

For developers

// Shorter batches on a host with a 30 second execution limit.
add_filter( 'wpmcf/jobs/batch_seconds', fn () => 10 );

A module registers a handler for its task type in its boot code; a handler must be idempotent, because a batch can be retried after a crash.