Document pantheon_clear_edge_keys(), pantheon_clear_edge_paths(), & pantheon_clear_edge_all()

The functions can be found in /srv/includes/pantheon.php (download via SFTP). Interestingly, one of the comments in the file indicates at least one of these functions used to be documented at https://pantheon.io/docs/articles/architecture/edge/varnish/caching-adva....

Draft docs below (in docblock form):

/**
 * Invalidates surrogate keys from the edge cache.
 *
 * Surrogate keys are collected in static cache. Later, a single request is
 * made to the edge cache in a shutdown function.
 *
 * @param array $keys
 *   An array of surrogate keys.
 *
 * @throws InvalidArgumentException
 */
function pantheon_clear_edge_keys(array $keys = array()) { }

/**
 * Invalidates specific paths from the edge cache.
 *
 * Requests are made to edge cache when this function is called. (i.e. They are
 * not collected and sent at the end of the request in a shutdown function.)
 *
 * @param array $paths
 *   An array of paths.
 *
 * @throws InvalidArgumentException
 */
function pantheon_clear_edge_paths($paths=array()) { }

/**
 * Invalidates the entire edge cache.
 *
 * @throws InvalidArgumentException
 */
function pantheon_clear_edge_all() { }

I think the important takeaway is that surrogate keys are batched and paths are not.

As a performance enhancement, pantheon_clear_edge_paths() could batch and then send in a shutdown function like pantheon_clear_edge_keys.