OSDev.org

The Place to Start for Operating System Developers
It is currently Tue Dec 18, 2018 4:34 am

All times are UTC - 6 hours




Post new topic Reply to topic  [ 9 posts ] 
Author Message
 Post subject: Should I use 'discard' or 'abandon' when name a function...
PostPosted: Thu May 10, 2018 1:13 pm 
Offline

Joined: Thu May 10, 2018 1:05 pm
Posts: 16
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!


Top
 Profile  
 
 Post subject: Re: Should I use 'discard' or 'abandon' when name a function
PostPosted: Thu May 10, 2018 1:20 pm 
Offline
Member
Member
User avatar

Joined: Sat Mar 31, 2012 3:07 am
Posts: 3308
Location: Chichester, UK
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.


Top
 Profile  
 
 Post subject: Re: Should I use 'discard' or 'abandon' when name a function
PostPosted: Thu May 10, 2018 5:03 pm 
Offline
Member
Member
User avatar

Joined: Mon Mar 05, 2012 11:23 am
Posts: 567
Location: Germany
For a function destroying a line, 'line_destroy()' sounds quite good. :P

_________________
-maxdev
Ghost OS / https://github.com/maxdev1/ghost


Top
 Profile  
 
 Post subject: Re: Should I use 'discard' or 'abandon' when name a function
PostPosted: Thu May 10, 2018 8:20 pm 
Offline
Member
Member

Joined: Mon Jul 25, 2016 6:54 pm
Posts: 148
Location: Adelaide, Australia
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.


Top
 Profile  
 
 Post subject: Re: Should I use 'discard' or 'abandon' when name a function
PostPosted: Fri May 11, 2018 12:48 am 
Offline

Joined: Thu May 10, 2018 1:05 pm
Posts: 16
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:
Code:
struct viline{
    char *buf;
    int len;
    int size;
    int flags;
};

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.


Top
 Profile  
 
 Post subject: Re: Should I use 'discard' or 'abandon' when name a function
PostPosted: Fri May 11, 2018 1:38 am 
Offline
Member
Member
User avatar

Joined: Fri Oct 03, 2008 4:13 am
Posts: 130
Location: Ogre, Latvia, EU
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 something looks overcomplicated, most likely it is.


Top
 Profile  
 
 Post subject: Re: Should I use 'discard' or 'abandon' when name a function
PostPosted: Fri May 11, 2018 3:22 am 
Offline
Member
Member

Joined: Fri Aug 19, 2016 10:28 pm
Posts: 351
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.


Top
 Profile  
 
 Post subject: Re: Should I use 'discard' or 'abandon' when name a function
PostPosted: Sat May 12, 2018 9:49 am 
Offline

Joined: Thu May 10, 2018 1:05 pm
Posts: 16
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.


Top
 Profile  
 
 Post subject: Re: Should I use 'discard' or 'abandon' when name a function
PostPosted: Sat May 12, 2018 10:01 am 
Offline

Joined: Thu May 10, 2018 1:05 pm
Posts: 16
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.


Top
 Profile  
 
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 9 posts ] 

All times are UTC - 6 hours


Who is online

Users browsing this forum: No registered users and 4 guests


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
Powered by phpBB © 2000, 2002, 2005, 2007 phpBB Group