commit 7929297cd6988e34bacd943674e1acf5d70905f3
parent 60cd584844a4582f0ee6ff3cd9e4bf7cbe5bcec5
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date: Mon, 17 Oct 2022 16:32:39 +0200
Rephrase the cookie documentation
Diffstat:
1 file changed, 29 insertions(+), 28 deletions(-)
diff --git a/include/clap/ext/params.h b/include/clap/ext/params.h
@@ -155,42 +155,43 @@ typedef struct clap_param_info {
clap_param_info_flags flags;
- // This value is optional and set by the plugin. The host will
- // set it on all subsequent events regarding this param_id
- // or set the cookie to nullptr if the host chooses to
- // not implement cookies.
+ // This value is optional and set by the plugin.
+ // Its purpose is to provide a fast access to the
+ // plugin parameter objects by caching its pointer.
+ // For instance:
//
- // The plugin must gracefully handle the case of a cookie
- // which is nullptr, but can safely assume any cookie
- // which is not nullptr is the value it issued.
- //
- // It is very strongly recommended that the host implement
- // cookies. Some plugins may have noticably reduced
- // performance when addressing params in hosts without cookies.
- //
- // The cookie's purpose is to provide a fast access to the
- // plugin parameter objects. For instance:
- //
- // in clap_plugin_params.get_info
+ // in clap_plugin_params.get_info():
// Parameter *p = findParameter(param_id);
// param_info->cookie = p;
//
- // later, in clap_plugin.process:
+ // later, in clap_plugin.process():
+ //
+ // Parameter *p = (Parameter *)event->cookie;
+ // if (!p) [[unlikely]]
+ // p = findParameter(event->param_id);
+ //
+ // where findParameter() is a function the plugin implements
+ // to map parameter ids to internal objects.
+ //
+ // The host will either provide the cookie as issued or nullptr
+ // in events addressing parameters.
+ //
+ // The plugin must gracefully handle the case of a cookie
+ // which is nullptr, but can safely assume any cookie
+ // which is not nullptr is the value it issued.
//
- // Parameter *p{nullptr};
- // if (evt->cookie) [[likely]]
- // p = (Parameter *)evt->cookie;
- // else
- // p = -- alternate mechanism --
+ // The host should provide the cookie if its retrival is cheaper
+ // than an hastable lookup, otherwise the plugin may as well do
+ // the parameter lookup.
//
- // where "alternate mechanism" is a mechanism the plugin implements
- // to map parameter ids to internal objects.
+ // TIP: the host may build a cached array of parameters info
+ // and internally work with parameter index, that way the retrival cost
+ // of the cookie is equivalent to an array access.
//
- // The host should make no assumption about the
- // value of the cookie other than passing it back to the plugin or
- // replacing it with nullptr.
+ // The host should make no assumption about the value of the cookie
+ // other than passing it back to the plugin or replacing it with nullptr.
//
- // Once set, the cookie is valid until invalidated by a call to
+ // Once set, the cookie is valid until invalidated by a call to
// clap_host_params->rescan(CLAP_PARAM_RESCAN_ALL) or when the plugin is
// destroyed.
void *cookie;