callout(9) really this complicated?

[Hans Petter Selasky]

On 07/04/14 06:15, John-Mark Gurney wrote:
> So, I was going to look at using callout(9) for some time delayed
> actions...  But upon reading the docs, a) the docs are inconsistent,
> and b) the docs only talk about requirements in other section...
>
> Is there a better interface?  If so, can we mark callout(9) deprecated?
> If not, I have some questions...
>
> If you want callout_drain to work properly, you have to add extra code
> to both your callout, and around the usage of it...
>
> callout_drain does not drain the callout:
>       However, the callout subsystem does guarantee that the callout will be
>       fully stopped before callout_drain() returns.
>
> Yet other parse of the docs say that you can depend upon the callout
> being fully stopped..  I've sent email to Ian (iedowse) about why he
> added this statement...
>
> Second, the amount of work you have to do to make sure you drain
> seems pretty crazy as documented in Avoiding Race Conditions...
>
> It seems like if I have created a callout w/ callout_init_mtx,
> that I shouldn't have to do extra work to make it work correctly...
>
> When calling _callout_stop_safe as callout_drain, there is no assert
> that the lock is held, though it is documented as requiring it by:
>       The function callout_drain() is identical to callout_stop() except that
>       it will wait for the callout to be completed if it is already in
>       progress.
>
> Maybe we need to add an additional statement here?  and assert that it
> isn't locked?
>
> Also, I have tried to follow the code, but it's complicated, so I'm
> hoping that I can get some help here.
>
> Thanks.
>

Hi,

Probably the documentation needs an update. The implementation is fine.

Basically like with many other multi processor APIs in the kernel:

start and stop operations needs to be locked, not because of callout 
internals, but because of your driver staying sync.

drain is always called unlocked.

--HPS