Merge pull request #414 from woocommerce/issue_411

Update docs for version 3.0

docs/api.md

@@ -13,7 +13,7 @@ The Action Scheduler API functions are designed to mirror the WordPress [WP-Cron
 
 Functions return similar values and accept similar arguments to their WP-Cron counterparts. The notable differences are:
 
-* `as_schedule_single_action()` & `as_schedule_recurring_action()` will return the post ID of the scheduled action rather than boolean indicating whether the event was scheduled
+* `as_schedule_single_action()` & `as_schedule_recurring_action()` will return the ID of the scheduled action rather than boolean indicating whether the event was scheduled
 * `as_schedule_recurring_action()` takes an interval in seconds as the recurring interval rather than an arbitrary string
 * `as_schedule_single_action()` & `as_schedule_recurring_action()` can accept a `$group` parameter to group different actions for the one plugin together.
 * the `wp_` prefix is substituted with `as_` and the term `event` is replaced with `action`
@@ -24,11 +24,34 @@ As mentioned in the [Usage - Load Order](/usage/#load-order) section, Action Sch
 
 Do not use Action Scheduler API functions prior to `'init'` hook with priority `1`. Doing so could lead to unexpected results, like data being stored in the incorrect location.
 
+## Function Reference / `as_enqueue_async_action()`
+
+### Description
+
+Enqueue an action to run one time, as soon as possible.
+
+### Usage
+
+```php
+as_enqueue_async_action( $hook, $args, $group )
+````
+
+### Parameters
+
+- **$hook** (string)(required) Name of the action hook. Default: _none_.
+- **$args** (array) Arguments to pass to callbacks when the hook triggers. Default: _`array()`_.
+- **$group** (array) The group to assign this job to. Default: _''_.
+
+### Return value
+
+(integer) the action's ID.
+
+
 ## Function Reference / `as_schedule_single_action()`
 
 ### Description
 
-Schedule an action to run one time.
+Schedule an action to run one time at some defined point in the future.
 
 ### Usage
 
@@ -45,7 +68,7 @@ as_schedule_single_action( $timestamp, $hook, $args, $group )
 
 ### Return value
 
-(integer) the action's ID in the [posts](http://codex.wordpress.org/Database_Description#Table_Overview) table.
+(integer) the action's ID.
 
 
 ## Function Reference / `as_schedule_recurring_action()`
@@ -70,7 +93,7 @@ as_schedule_recurring_action( $timestamp, $interval_in_seconds, $hook, $args, $g
 
 ### Return value
 
-(integer) the action's ID in the [posts](http://codex.wordpress.org/Database_Description#Table_Overview) table.
+(integer) the action's ID.
 
 
 ## Function Reference / `as_schedule_cron_action()`
@@ -95,14 +118,14 @@ as_schedule_cron_action( $timestamp, $schedule, $hook, $args, $group )
 
 ### Return value
 
-(integer) the action's ID in the [posts](http://codex.wordpress.org/Database_Description#Table_Overview) table.
+(integer) the action's ID.
 
 
 ## Function Reference / `as_unschedule_action()`
 
 ### Description
 
-Cancel the next occurrence of a job.
+Cancel the next occurrence of a scheduled action.
 
 ### Usage
 
@@ -120,6 +143,28 @@ as_unschedule_action( $hook, $args, $group )
 
 (null)
 
+## Function Reference / `as_unschedule_all_actions()`
+
+### Description
+
+Cancel all occurrences of a scheduled action.
+
+### Usage
+
+```php
+as_unschedule_action( $hook, $args, $group )
+````
+
+### Parameters
+
+- **$hook** (string)(required) Name of the action hook.
+- **$args** (array) Arguments to pass to callbacks when the hook triggers. Default: _`array()`_.
+- **$group** (array) The group to assign this job to. Default: _''_.
+
+### Return value
+
+(null)
+
 
 ## Function Reference / `as_next_scheduled_action()`
 

docs/index.md

@@ -3,7 +3,7 @@ title: Action Scheduler - Background Processing Job Queue for WordPress
 ---
 ## WordPress Job Queue with Background Processing
 
-Action Scheduler is a library for triggering a WordPress hook to run at some time in the future. Each hook can be scheduled with unique data, to allow callbacks to perform operations on that data. The hook can also be scheduled to run on one or more occassions.
+Action Scheduler is a library for triggering a WordPress hook to run at some time in the future (or as soon as possible, in the case of an async action). Each hook can be scheduled with unique data, to allow callbacks to perform operations on that data. The hook can also be scheduled to run on one or more occassions.
 
 Think of it like an extension to `do_action()` which adds the ability to delay and repeat a hook.
 
@@ -21,25 +21,25 @@ Action Scheduler is specifically designed for distribution in WordPress plugins
 
 ### How it Works
 
-Action Scheduler uses a WordPress [custom post type](http://codex.wordpress.org/Post_Types), creatively named `scheduled-action`, to store the hook name, arguments and scheduled date for an action that should be triggered at some time in the future.
+Action Scheduler stores the hook name, arguments and scheduled date for an action that should be triggered at some time in the future.
 
-The scheduler will attempt to run every minute by attaching itself as a callback to the `'action_scheduler_run_schedule'` hook, which is scheduled using WordPress's built-in [WP-Cron](http://codex.wordpress.org/Function_Reference/wp_cron) system.
+The scheduler will attempt to run every minute by attaching itself as a callback to the `'action_scheduler_run_schedule'` hook, which is scheduled using WordPress's built-in [WP-Cron](http://codex.wordpress.org/Function_Reference/wp_cron) system. Once per minute on, it will also check on the `'shutdown'` hook of WP Admin requests whether there are pending actions, and if there are, it will initiate a queue via an async loopback request.
 
-When triggered, Action Scheduler will check for posts of the `scheduled-action` type that have a `post_date` at or before this point in time i.e. actions scheduled to run now or at sometime in the past.
+When triggered, Action Scheduler will check for scheduled actions that have a due date at or before this point in time i.e. actions scheduled to run now or at sometime in the past. Action scheduled to run asynchronously, i.e. not scheduled, have a zero date, meaning they will always be due no matter when the check occurs.
 
 ### Batch Processing Background Jobs
 
-If there are actions to be processed, Action Scheduler will stake a unique claim for a batch of 20 actions and begin processing that batch. The PHP process spawned to run the batch will then continue processing batches of 20 actions until it times out or exhausts available memory.
+If there are actions to be processed, Action Scheduler will stake a unique claim for a batch of 25 actions and begin processing that batch. The PHP process spawned to run the batch will then continue processing batches of 25 actions until it uses 90% of available memory or has been processing for 30 seconds.
 
-If your site has a large number of actions scheduled to run at the same time, Action Scheduler will process more than one batch at a time. Specifically, when the `'action_scheduler_run_schedule'` hook is triggered approximately one minute after the first batch began processing, a new PHP process will stake a new claim to a batch of actions which were not claimed by the previous process. It will then begin to process that batch.
+At that point, if there are additional actions to process, an asynchronous loopback request will be made to the site to continue processing actions in a new request.
 
-This will continue until all actions are processed using a maximum of 5 concurrent queues.
+This process and the loopback requests will continue until all actions are processed.
 
 ### Housekeeping
 
-Before processing a batch, the scheduler will remove any existing claims on actions which have been sitting in a queue for more than five minutes.
+Before processing a batch, the scheduler will remove any existing claims on actions which have been sitting in a queue for more than five minutes (or more specifically, 10 times the allowed time limit, which defaults to 30 seconds).
 
-Action Scheduler will also trash any actions which were completed more than a month ago.
+Action Scheduler will also trash any actions which were completed or canceled more than a month ago.
 
 If an action runs for more than 5 minutes, Action Scheduler will assume the action has timed out and will mark it as failed. However, if all callbacks attached to the action were to successfully complete sometime after that 5 minute timeout, its status would later be updated to completed.
 
@@ -49,11 +49,11 @@ Did your background job run?
 
 Never be left wondering with Action Scheduler's built-in record keeping.
 
-All events for each action are logged in the [comments table](http://codex.wordpress.org/Database_Description#Table_Overview) and displayed in the [administration interface](/admin/).
+All events for each action are logged in the `actionscheduler_logs` table and displayed in the [administration interface](/admin/).
 
 The events logged by default include when an action:
  * is created
- * starts
+ * starts (including details of how it was run, e.g. via [WP CLI](/wp-cli/) or WP Cron)
  * completes
  * fails
 
@@ -63,6 +63,6 @@ Actions can also be grouped together using a custom taxonomy named `action-group
 
 ## Credits
 
-Action Scheduler is developed and maintained by [Automattic](http://automattic.com/) with significant early development completed by [Flightless](https://flightless.us/).
+Action Scheduler is developed and maintained by folks at [Automattic](http://automattic.com/) with significant early development completed by [Flightless](https://flightless.us/).
 
 Collaboration is cool. We'd love to work with you to improve Action Scheduler. [Pull Requests](https://github.com/woocommerce/action-scheduler/pulls) welcome.

docs/perf.md

@@ -4,20 +4,21 @@ description: Learn how to do WordPress background processing at scale by tuning
 ---
 # Background Processing at Scale
 
-Action Scheduler's default processing is designed to work reliably across all different hosting environments. In order to achieve that, the default processing thresholds are very conservative.
+Action Scheduler's default processing is designed to work reliably across all different hosting environments. In order to achieve that, the default processing thresholds are more conservative than many servers could support.
 
-Specifically, Action Scheduler will only process actions until:
+Specifically, Action Scheduler will only process actions in a request until:
 
 * 90% of available memory is used
 * processing another 3 actions would exceed 30 seconds of total request time, based on the average processing time for the current batch
+* in a single concurrent queue
 
-On sites with large queues, this can result in very slow processing time.
+While Action Scheduler will initiate an asychronous loopback request to process additional actions, on sites with very large queues, this can result in slow processing times.
 
-While using [WP CLI to process queues](/wp-cli/) is the best approach to increasing processing speed, on occasion, that is not a viable option. In these cases, it's also possible to increase the processing thresholds in Action Scheduler to increase the rate at which actions are processed by the default WP Cron queue runner.
+While using [WP CLI to process queues](/wp-cli/) is the best approach to increasing processing speed, on occasion, that is not a viable option. In these cases, it's also possible to increase the processing thresholds in Action Scheduler to increase the rate at which actions are processed by the default queue runner.
 
 ## Increasing Time Limit
 
-By default, Action Scheduler will only process actions for a maximum of 30 seconds. This time limit minimises the risk of a script timeout on unknown hosting environments, some of which enforce 30 second timeouts.
+By default, Action Scheduler will only process actions for a maximum of 30 seconds in each request. This time limit minimises the risk of a script timeout on unknown hosting environments, some of which enforce 30 second timeouts.
 
 If you know your host supports longer than this time limit for web requests, you can increase this time limit. This allows more actions to be processed in each request and reduces the lag between processing each queue, greatly speeding up the processing rate of scheduled actions.
 
@@ -38,7 +39,7 @@ Some of the known host time limits are:
 
 ## Increasing Batch Size
 
-By default, Action Scheduler will claim a batch of 25 actions. This small batch size is because the default time limit is only 30 seconds; however, if you know your actions are processing very quickly, e.g. taking microseconds not seconds, or that you have more than 30 second available to process each batch, increasing the batch size can improve performance.
+By default, Action Scheduler will claim a batch of 25 actions. This small batch size is because the default time limit is only 30 seconds; however, if you know your actions are processing very quickly, e.g. taking microseconds not seconds, or that you have more than 30 second available to process each batch, increasing the batch size can slightly improve performance.
 
 This is because claiming a batch has some overhead, so the less often a batch needs to be claimed, the faster actions can be processed.
 
@@ -53,9 +54,9 @@ add_filter( 'action_scheduler_queue_runner_batch_size', 'eg_increase_action_sche
 
 ## Increasing Concurrent Batches
 
-By default, Action Scheduler will run up to 5 concurrent batches of actions. This is to prevent consuming all the available connections or processes on your webserver.
+By default, Action Scheduler will run only one concurrent batches of actions. This is to prevent consuming a lot of available connections or processes on your webserver.
 
-However, your server may allow a large number of connection, for example, because it has a high value for Apache's `MaxClients` setting or PHP-FPM's `pm.max_children` setting.
+However, your server may allow a large number of connections, for example, because it has a high value for Apache's `MaxClients` setting or PHP-FPM's `pm.max_children` setting.
 
 If this is the case, you can use the `'action_scheduler_queue_runner_concurrent_batches'` filter to increase the number of concurrent batches allowed, and therefore speed up processing large numbers of actions scheduled to be processed simultaneously.
 
@@ -68,13 +69,15 @@ function eg_increase_action_scheduler_concurrent_batches( $concurrent_batches )
 add_filter( 'action_scheduler_queue_runner_concurrent_batches', 'eg_increase_action_scheduler_concurrent_batches' );
 ```
 
+> WARNING: because of the async queue runner introduced in Action Scheduler 3.0 will continue asynchronous loopback requests to process actions, increasing the number of concurrent batches can substantially increase server load and take down a site. [WP CLI](/wp-cli/) is a better method to achieve higher throughput.
+
 ## Increasing Initialisation Rate of Runners
 
 By default, Action scheduler initiates at most one queue runner every time the `'action_scheduler_run_queue'` action is triggered by WP Cron.
 
-Because this action is only triggered at most once every minute, if a queue is only allowed to process for one minute, then there will never be more than one queue processing actions, greatly reducing the processing rate.
+Because this action is only triggered at most once every minute, then there will rarely be more than one queue processing actions even if the concurrent runners is increased.
 
-To handle larger queues on more powerful servers, it's a good idea to initiate additional queue runners whenever the `'action_scheduler_run_queue'` action is run.
+To handle larger queues on more powerful servers, it's possible to initiate additional queue runners whenever the `'action_scheduler_run_queue'` action is run.
 
 That can be done by initiated additional secure requests to our server via loopback requests.
 
@@ -122,6 +125,8 @@ function eg_create_additional_runners() {
 add_action( 'wp_ajax_nopriv_eg_create_additional_runners', 'eg_create_additional_runners', 0 );
 ```
 
+> WARNING: because of the processing rate of scheduled actions, this kind of increase can very easily take down a site. Use only on high powered servers and be sure to test before attempting to use it in production.
+
 ## High Volume Plugin
 
 It's not necessary to add all of this code yourself, there is a handy plugin to get access to each of these increases - the [Action Scheduler - High Volume](https://github.com/woocommerce/action-scheduler-high-volume) plugin.