.. versionadded:: 2016.11.0

    The Salt fileserver caches the files/directories/symlinks for each
    fileserver backend and environment as they are requested. This is done to
    help the fileserver scale better. Without this caching, when
    hundreds/thousands of minions simultaneously ask the master what files are
    available, this would cause the master's CPU load to spike as it obtains
    the same information separately for each minion.

    saltenv
        By default, this runner will clear the file list caches for all
        environments. This argument allows for a list of environments to be
        passed, to clear more selectively. This list can be passed either as a
        comma-separated string, or a Python list.

    backend
        Similar to the ``saltenv`` parameter, this argument will restrict the
        cache clearing to specific fileserver backends (the default behavior is
        to clear from all enabled fileserver backends). This list can be passed
        either as a comma-separated string, or a Python list.

    .. note:
        The maximum age for the cached file lists (i.e. the age at which the
        cache will be disregarded and rebuilt) is defined by the
        :conf_master:`fileserver_list_cache_time` configuration parameter.

    Since the ability to clear these caches is often required by users writing
    custom runners which add/remove files, this runner can easily be called
    from within a custom runner using any of the following examples:

    .. code-block:: python

        # Clear all file list caches
        __salt__['fileserver.clear_file_list_cache']()
        # Clear just the 'base' saltenv file list caches
        __salt__['fileserver.clear_file_list_cache'](saltenv='base')
        # Clear just the 'base' saltenv file list caches from just the 'roots'
        # fileserver backend
        __salt__['fileserver.clear_file_list_cache'](saltenv='base', backend='roots')
        # Clear all file list caches from the 'roots' fileserver backend
        __salt__['fileserver.clear_file_list_cache'](backend='roots')

    .. note::
        In runners, the ``__salt__`` dictionary will likely be renamed to
        ``__runner__`` in a future Salt release to distinguish runner functions
        from remote execution functions. See `this GitHub issue`_ for
        discussion/updates on this.

    .. _`this GitHub issue`: https://github.com/saltstack/salt/issues/34958

    If using Salt's Python API (not a runner), the following examples are
    equivalent to the ones above:

    .. code-block:: python

        import salt.config
        import salt.runner

        opts = salt.config.master_config('/etc/salt/master')
        opts['fun'] = 'fileserver.clear_file_list_cache'

        # Clear all file list_caches
        opts['arg'] = []  # No arguments
        runner = salt.runner.Runner(opts)
        cleared = runner.run()

        # Clear just the 'base' saltenv file list caches
        opts['arg'] = ['base', None]
        runner = salt.runner.Runner(opts)
        cleared = runner.run()

        # Clear just the 'base' saltenv file list caches from just the 'roots'
        # fileserver backend
        opts['arg'] = ['base', 'roots']
        runner = salt.runner.Runner(opts)
        cleared = runner.run()

        # Clear all file list caches from the 'roots' fileserver backend
        opts['arg'] = [None, 'roots']
        runner = salt.runner.Runner(opts)
        cleared = runner.run()


    This function will return a dictionary showing a list of environments which
    were cleared for each backend. An empty return dictionary means that no
    changes were made.

    CLI Examples:

    .. code-block:: bash

        # Clear all file list caches
        salt-run fileserver.clear_file_list_cache
        # Clear just the 'base' saltenv file list caches
        salt-run fileserver.clear_file_list_cache saltenv=base
        # Clear just the 'base' saltenv file list caches from just the 'roots'
        # fileserver backend
        salt-run fileserver.clear_file_list_cache saltenv=base backend=roots
        # Clear all file list caches from the 'roots' fileserver backend
        salt-run fileserver.clear_file_list_cache backend=roots

def clear_file_list_cache(saltenv=None, backend=None):
    '''
    .. versionadded:: 2016.11.0

    The Salt fileserver caches the files/directories/symlinks for each
    fileserver backend and environment as they are requested. This is done to
    help the fileserver scale better. Without this caching, when
    hundreds/thousands of minions simultaneously ask the master what files are
    available, this would cause the master's CPU load to spike as it obtains
    the same information separately for each minion.

    saltenv
        By default, this runner will clear the file list caches for all
        environments. This argument allows for a list of environments to be
        passed, to clear more selectively. This list can be passed either as a
        comma-separated string, or a Python list.

    backend
        Similar to the ``saltenv`` parameter, this argument will restrict the
        cache clearing to specific fileserver backends (the default behavior is
        to clear from all enabled fileserver backends). This list can be passed
        either as a comma-separated string, or a Python list.

    .. note:
        The maximum age for the cached file lists (i.e. the age at which the
        cache will be disregarded and rebuilt) is defined by the
        :conf_master:`fileserver_list_cache_time` configuration parameter.

    Since the ability to clear these caches is often required by users writing
    custom runners which add/remove files, this runner can easily be called
    from within a custom runner using any of the following examples:

    .. code-block:: python

        # Clear all file list caches
        __salt__['fileserver.clear_file_list_cache']()
        # Clear just the 'base' saltenv file list caches
        __salt__['fileserver.clear_file_list_cache'](saltenv='base')
        # Clear just the 'base' saltenv file list caches from just the 'roots'
        # fileserver backend
        __salt__['fileserver.clear_file_list_cache'](saltenv='base', backend='roots')
        # Clear all file list caches from the 'roots' fileserver backend
        __salt__['fileserver.clear_file_list_cache'](backend='roots')

    .. note::
        In runners, the ``__salt__`` dictionary will likely be renamed to
        ``__runner__`` in a future Salt release to distinguish runner functions
        from remote execution functions. See `this GitHub issue`_ for
        discussion/updates on this.

    .. _`this GitHub issue`: https://github.com/saltstack/salt/issues/34958

    If using Salt's Python API (not a runner), the following examples are
    equivalent to the ones above:

    .. code-block:: python

        import salt.config
        import salt.runner

        opts = salt.config.master_config('/etc/salt/master')
        opts['fun'] = 'fileserver.clear_file_list_cache'

        # Clear all file list_caches
        opts['arg'] = []  # No arguments
        runner = salt.runner.Runner(opts)
        cleared = runner.run()

        # Clear just the 'base' saltenv file list caches
        opts['arg'] = ['base', None]
        runner = salt.runner.Runner(opts)
        cleared = runner.run()

        # Clear just the 'base' saltenv file list caches from just the 'roots'
        # fileserver backend
        opts['arg'] = ['base', 'roots']
        runner = salt.runner.Runner(opts)
        cleared = runner.run()

        # Clear all file list caches from the 'roots' fileserver backend
        opts['arg'] = [None, 'roots']
        runner = salt.runner.Runner(opts)
        cleared = runner.run()


    This function will return a dictionary showing a list of environments which
    were cleared for each backend. An empty return dictionary means that no
    changes were made.

    CLI Examples:

    .. code-block:: bash

        # Clear all file list caches
        salt-run fileserver.clear_file_list_cache
        # Clear just the 'base' saltenv file list caches
        salt-run fileserver.clear_file_list_cache saltenv=base
        # Clear just the 'base' saltenv file list caches from just the 'roots'
        # fileserver backend
        salt-run fileserver.clear_file_list_cache saltenv=base backend=roots
        # Clear all file list caches from the 'roots' fileserver backend
        salt-run fileserver.clear_file_list_cache backend=roots
    '''
    fileserver = salt.fileserver.Fileserver(__opts__)
    load = {'saltenv': saltenv, 'fsbackend': backend}
    return fileserver.clear_file_list_cache(load=load)