Cookies are mandatory for hosts!!

[sagantech]

So I spent a large part of my Saturday debugging a crash in my host immediately after an automation event was sent to a plugin (TAL UNO LX). 100% reproducible. It turns out that the host MUST propagate the "cookie" field of all parameter automations or else certain plugins will crash or worse. The "cookie" field should be better documented and is currently documented as:

// This value is optional and set by the plugin.
// Its purpose is to provide a fast access to the plugin parameter:
//
// Parameter p = findParameter(param_id);
// param_info->cookie = p;
//
// / and later on */
// Parameter *p = (Parameter *)cookie;
//
// It is invalidated on clap_host_params->rescan(CLAP_PARAM_RESCAN_ALL) and when the plugin is
// destroyed.

This value is not optional for a host.

[robbert-vdh]

Hosts should propagate these cookies in the parameter events since it's a useful optimization, but I also feel like the plugin should be able to handle missing cookies. It's still a pointer, and you should never assume a pointer is not null without checking.

[baconpaul]

I completely disagree with this @robbert-vdh

the cookie is a pointer that is handed by the plugin so it can do internal state management and optimization. The only activity we could take if cookies were null in surge is "don't run". They are not optional.

@sagantech I agree that documentation can be better to make the importance of these much more obvious!

[sagantech]

I agree with @robbert-vdh about using a pointer without null checking. It would be better for the host not to crash (inside the plug-in) in that case even if the plug-in is non-functional.
The main point however is as @baconpaul states:

documentation can be better to make the importance of these much more obvious!

[baconpaul]

So to be pedantic: we aren't using a pointer without null checking. We are using a pointer we handed to you to give back to us.

And while a null check is easy I guess a defensive check for any other random value isn't right? The job of the host is to return the pointer which was given to it from the plugin! I don't know how to check if it doesn't without maintaining a map from param id to cookie, which is what the cookie avoids.

So I don't think there is a useful check the plugin can do which is defensive other than make exactly the data structure the cookie exists to avoid using!

[robbert-vdh]

And while a null check is easy I guess a defensive check for any other random value isn't right?

If the cookie field contains garbage values from uninitialized memory then the host triggered UB (always zero out/initialize your structs), so you can't catch that. So that's a host bug.

[sagantech]

I agree.

[sagantech]

I don't think this is an issue if the comment in the header file is changed.

[baconpaul]

Totally agree!

[baconpaul]

Here's a proposed rewrite of that comment

// This value is optionally set by the plugin. If, however, the plugin
// chooses to set it the host *must* set that value on every subsequent
// event which references a parameter. The host should view this value as
// a required, plugin provided, opaque, immutable value for all subsequent communications.
//
// When `clap_host_params->rescan(CLAP_PARAM_RESCAN_ALL)` the cookie is
// invalidated and the plugin can provide a new cookie value (or the same cookie value).
// After the plugin is destroyed, the cookie is no longer valid. 
//
// The host should make no assumptions about the cookie, what it points to, or if
// any value of the cookie, including nullptr, is special.
//
// The purpose to allow the plugin fast access to an internal plugin parameter
// data structure. For instance, if a plugin has its own internal class "MyParam"
// you could imagine code during the CLAP setup like
//
// auto *p = findParameter(param_id); 
// param_info->cookie = p;
//
// and then subsequently
// 
// auto *p = (MyParam *)cookie;
//
// This allows the plugin to avoid maintaining and using maps from plugin ids to parameter objects 
// during frequent events like parameter updates.

[baconpaul]

yeah exactly.

The mental model to have with cookies (although plugins can do anything they want) is that the plugin has an internal list of parameter objects. There's only one place in the clap API where the parameters are addressed by index and that's get_info so that's where you hand out IDs (which are what is used everywhere else to refer to parameters, including all persistence, streaming, automation).

To avoid plugins having to do ID -> object lookups using an internal map, the plugins can also hand a free pointer to the host for later reference, so the full address of a parameter is (id, cookie*) basically, although the plugin can ignore cookie.

In a rescan, the plugin can change parameter count. So for instance the CLAP API allows a plugin to tell the host to request a full param rescan in which case it may add params - those would have new cookies. Or remove them - that would invalidate old cookies.

But the by far most common case with CLAP will be that the cookie is a pointer to the juce::parameter or iplug::parameter object or what not,.

[TaleTN]

I feel I'm going in circles, but let's have at least one more try: :-)

So setting the cookie in get_info() isn't optional, but using the cookie elsewhere in the plugin is optional. Correct?

[sagantech]

If you are developing a plug-in (not a host) setting the cookie IS optional.

[TaleTN]

But isn't the host still required to propagate the cookie, even if the plugin has chosen to not set/initialize it? If so, then this will probably work just fine in practice, but strictly speaking, AFAIK reading an uninitialized variable is undefined behavior in C.

[baconpaul]

The host may want to initialize the info structure before it calls the get info
But a void* is just a value. The host gets it and sends it back.