OSDev.org

I am writing a text parser, and now I have a data structure called 'struct line'. I want to write a function destroying it, i.e. release its internal buffer and so on. Should I name it 'line_abandon()' or 'line_discard()' ? I don't know the difference between the two words.

If the function detail I supplied is not enough, please tell me and I will write more.

Thank you!

It is relatively unimportant what you call the function. Just use whatever you are most comfortable with. Your comments will tell anyone looking at your code exactly what the function does and what data it modifies.

For a function destroying a line, 'line_destroy()' sounds quite good.

As mentioned, as long as you know what it means it's more a matter of personal preference. However, generally "free" is used in C libraries because it specifically implies to the user that the resources used are to be deallocated. Abandon and discard may be confusing, because both imply no longer using something, but not actually destroying it.

StudlyCaps wrote: Abandon and discard may be confusing, because both imply no longer using something, but not actually destroying it.

Thanks for your replies. @iansjack @max
I think I should describe this function in more detail:
This is the 'line' structure: The function 'viline_discard(struct viline *line)' works like this:
check 'viline->flags' to see whether this line is sharing the string buffer(namely 'viline->buf') with some other(s).
if yes, decrement the reference count. if no or the reference count turns zero, call free() to release the buffer.
This function won't touch any field of the 'viline' structure, but after it returns, the 'viline' turns into a meaningless structure never holding string buffer any more, and this structure can be recycled.
So I think viline_destroy() is not vivid.

The function you described is essentially a destructor. It does not matter how the shared buffer is handled internally, you are destroying the instance of viline by calling it.

But, since you do not like 'destroy', may I suggest 'dispose'?

If you are implementing a shared object with reference counting, the standard names are acquire and release, or retain and release. That is for explicit increment and decrement of the reference/user count.

If you are implementing copy on write and you use reference counting internally, then you should use create, copy, destroy and modifier/accessor methods and manage the reference counts as necessary, but you don't need to expose acquire and release methods. Copying will automatically acquire the internal object reference and destroy will automatically release it.

If you allow eager cleanup, before the object is destroyed, then the standard name is dispose as Velko suggested. The destroy method checks if the object is already disposed, and if it is, avoids freeing the internal buffer and directly frees the structure itself. Or something similar. Depends on the purpose of the early cleanup.

It always helps to think in terms of antonym pairs. If I wanted to evaluate whether the use of abandon feels appropriate, I will try to think of the opposite matching verb. Abandon feels like the opposite of join or adopt, or something. It can be considered the opposite of obtain, but really, I think it is not used that way. Here are some technical antonym pairs:
initialize - finalize/uninitialize
retain - dispose
prepare - cleanup
acquire - release
make - discard (not antonym, but symmetrical for technical usage)
create - destroy
bind - free
allocate - deallocate
open - close

A few freestanding finishers:
(probably setup -) reset
terminate
kill

Words are rarely properly matched with their true antonyms in common practice. For example, retain is matched with release, allocate with free, initialize with terminate or dispose, setup with cleanup, create with kill or close, etc. But thinking of the antonym helps to evaluate the context usage of the verb. Some finishers are useful in very specific cases - i.e. reset for container structures or with the builder pattern (e.g. adding points to polyline), to restart the building process.

P.S. - Reference counting and sharing can become challenging when combined with concurrency - i.e. threads and SMP; the count has to be modified atomically and the buffer has to be manipulated under a mutex or reader/writer lock. I'm mentioning it in case you end up exposing the structure to threads later.

simeonz wrote:If you are implementing a shared object ....

I finally finished reading your post, with a dictionary in hand
Thanks for your kind reply. I think I will also review it in future.

Velko wrote:The function you described is essentially a destructor. It does not matter how the shared buffer is handled internally, you are destroying the instance of viline by calling it.

But, since you do not like 'destroy', may I suggest 'dispose'?

Yes, you remind me. It works like a destructor in behavior, may be thinking in an OO way is a good choice.