Re: [PATCH 3/4] ring-buffer: add ring_buffer_discard_commit

[Steven Rostedt]

On Wed, 1 Apr 2009, Andrew Morton wrote:

> On Thu, 02 Apr 2009 01:27:24 -0400 Steven Rostedt <rostedt@xxxxxxxxxxx> wrote:
> 
> > From: Steven Rostedt <srostedt@xxxxxxxxxx>
> > 
> > The ring_buffer_discard_commit is similar to ring_buffer_event_discard
> > but it can only be done on an event that has yet to be commited.
> > Unpredictable results can happen otherwise.
> > 
> > The main difference between ring_buffer_discard_commit and
> > ring_buffer_event_discard is that ring_buffer_discard_commit will try
> > to free the data in the ring buffer if nothing has addded data
> > after the reserved event. If something did, then it acts almost the
> > same as ring_buffer_event_discard followed by a
> > ring_buffer_unlock_commit.
> > 
> > Note, either ring_buffer_commit_discard and ring_buffer_unlock_commit
> > can be called on an event, not both.
> > 
> > This commit also exports both discard functions to be usable by
> > GPL modules.
> > 
> > ...
> >
> > +/*
> > + * ring_buffer_event_discard can discard any event in the ring buffer.
> > + *   it is up to the caller to protect against a reader from
> > + *   consuming it or a writer from wrapping and replacing it.
> > + *
> > + * No external protection is needed if this is called before
> > + * the event is commited. But in that case it would be better to
> > + * use ring_buffer_discard_commit.
> > + *
> > + * Note, if an event that has not been committed is discarded
> > + * with ring_buffer_event_discard, it must still be committed.
> > + */
> >  void ring_buffer_event_discard(struct ring_buffer_event *event);
> >  
> > ...
> >
> >  /**
> > + * ring_buffer_event_discard - discard any event in the ring buffer
> > + * @event: the event to discard
> > + *
> > + * Sometimes a event that is in the ring buffer needs to be ignored.
> > + * This function lets the user discard an event in the ring buffer
> > + * and then that event will not be read later.
> > + *
> > + * Note, it is up to the user to be careful with this, and protect
> > + * against races. If the user discards an event that has been consumed
> > + * it is possible that it could corrupt the ring buffer.
> > + */
> > +void ring_buffer_event_discard(struct ring_buffer_event *event)
> > +{
> > +	event->type = RINGBUF_TYPE_PADDING;
> > +	/* time delta must be non zero */
> > +	if (!event->time_delta)
> > +		event->time_delta = 1;
> > +}
> > +EXPORT_SYMBOL_GPL(ring_buffer_event_discard);
> 
> Seems a bit cumbersome to document the interface partly in the .h file
> and partly in the .c file?
> 
> Doing all of it in the .c file would be typical.

I thought the full documentation was in the .c file. I actually added the 
.h documentation because I was afraid that developers would just look at 
the header file and pick the wrong option. The kernel-doc documentation is 
for the C file. The .h file was a quick reference for those that wanted to 
know which function they needed. Since the two are similar, I wanted to 
make it clear what the differences were both in the .c and .h files.

It would even remind me on which to use ;-)

-- Steve

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/