[Cs-dev] API naming consistency
Date | 2013-06-21 16:13 |
From | Andres Cabrera |
Subject | [Cs-dev] API naming consistency |
Attachments | None None |
Hi, I was thinking it might be good to have more consistency in the naming of API functions. Please let me know if you agree or disagree with these changes and I can do them:PUBLIC CSOUND *csoundCreate(void *hostData); PUBLIC void csoundDestroy(CSOUND *); PUBLIC void *csoundCreateThreadLock(void); PUBLIC void csoundDestroyThreadLock(void *lock); PUBLIC void *csoundCreateMutex(int isRecursive); PUBLIC void csoundDestroyMutex(void *mutex_); PUBLIC void *csoundCreateBarrier(unsigned int max); PUBLIC int csoundDestroyBarrier(void *barrier); PUBLIC int csoundCreateGlobalVariable(CSOUND *, PUBLIC int csoundDestroyGlobalVariable(CSOUND *, const char *name); Creates without paired Destroys: I think Destroy should be used instead of Free: PUBLIC void *csoundCreateCircularBuffer(CSOUND *csound, int size); PUBLIC void csoundFreeCircularBuffer(CSOUND *csound, void *circularbuffer); Destroy without Create: I think Create should be used instead of Enable: PUBLIC void csoundEnableMessageBuffer(CSOUND *csound, int toStdOut); void PUBLIC csoundDestroyMessageBuffer(CSOUND *csound); Different: Not sure what to do about these, maybe they should stay as they are: PUBLIC int csoundNewOpcodeList(CSOUND *, opcodeListEntry **opcodelist); PUBLIC void csoundDisposeOpcodeList(CSOUND *, opcodeListEntry *opcodelist); These are probably OK: PUBLIC void csoundDeleteTree(CSOUND *csound, TREE *tree); PUBLIC void csoundDeleteChannelList(CSOUND *, controlChannelInfo_t *lst); PUBLIC void csoundDeleteUtilityList(CSOUND *, char **lst); PUBLIC void *csoundCreateThread(uintptr_t (*threadRoutine)(void *), PUBLIC uintptr_t csoundJoinThread(void *thread); (There is no need for DestroyThread, right?) 2) Dev list function names csoundMIDIDevList should be changed to: csoundGetMIDIDevList csoundAudioDevList should be changed to: csoundGetAudioDevList 3) Callback setters: I think "Register" is better than "Set" but maybe since there is only one "Register" change this one to "Set". Additionally there is one "generic" callback setter that can only set one callback, so make this an explicit and definite callbakc setter: Callbacks: PUBLIC void csoundSetFileOpenCallback(CSOUND *p, PUBLIC void csoundSetPlayopenCallback(CSOUND *, PUBLIC void csoundSetRtplayCallback(CSOUND *, PUBLIC void csoundSetRecopenCallback(CSOUND *, PUBLIC void csoundSetRtrecordCallback(CSOUND *, PUBLIC void csoundSetRtcloseCallback(CSOUND *, void (*rtclose__)(CSOUND *)); PUBLIC void csoundSetAudioDeviceListCallback(CSOUND *csound, PUBLIC void csoundSetExternalMidiInOpenCallback(CSOUND *, PUBLIC void csoundSetExternalMidiReadCallback(CSOUND *, PUBLIC void csoundSetExternalMidiInCloseCallback(CSOUND *, PUBLIC void csoundSetExternalMidiOutOpenCallback(CSOUND *, PUBLIC void csoundSetExternalMidiWriteCallback(CSOUND *, PUBLIC void csoundSetExternalMidiOutCloseCallback(CSOUND *, PUBLIC void csoundSetExternalMidiErrorStringCallback(CSOUND *, PUBLIC void csoundSetMIDIDeviceListCallback(CSOUND *csound, PUBLIC void csoundSetCscoreCallback(CSOUND *, void (*cscoreCallback_)(CSOUND *)); PUBLIC void csoundSetDefaultMessageCallback( void (*csoundMessageCallback_)(CSOUND *, PUBLIC void csoundSetMessageCallback(CSOUND *, void (*csoundMessageCallback_)(CSOUND *, csoundSetInputChannelCallback(CSOUND *csound, channelCallback_t inputChannelCalback); csoundSetOutputChannelCallback(CSOUND *csound, channelCallback_t outputChannelCalback); PUBLIC int csoundRegisterSenseEventCallback(CSOUND *, PUBLIC int csoundSetCallback(CSOUND *, int (*func)(void *userData, void *p, PUBLIC void csoundRemoveCallback(CSOUND *, PUBLIC void csoundSetMakeGraphCallback(CSOUND *, void (*makeGraphCallback_)(CSOUND *, PUBLIC void csoundSetDrawGraphCallback(CSOUND *, void (*drawGraphCallback_)(CSOUND *, PUBLIC void csoundSetKillGraphCallback(CSOUND *, void (*killGraphCallback_)(CSOUND *, PUBLIC void csoundSetExitGraphCallback(CSOUND *, int (*exitGraphCallback_)(CSOUND *)); PUBLIC void csoundSetYieldCallback(CSOUND *, int (*yieldCallback_)(CSOUND *)); PUBLIC void csoundSetInputValueCallback(CSOUND *, PUBLIC void csoundSetOutputValueCallback(CSOUND *, PUBLIC void csoundSetChannelIOCallback(CSOUND *, CsoundChannelIOCallback_t func); 4) For consistency should all typedef names be changed to uppercase? or all to lower case ending in "_t"? Cheers, Andrés |
Date | 2013-06-21 16:17 |
From | Michael Gogins |
Subject | Re: [Cs-dev] API naming consistency |
Attachments | None None |
I think your suggestions are good. I wish they had been implemented earlier than rc3 but I still think they should be implemented. I think typenames should be _t. This would also be an opportunity to enforce const correctness, get rid of macros in favor of enums or inlines at least in the public API, fix up csound.hpp to exactly reflect the C API, etc. Thanks, Mike =========================== Michael GoginsIrreducible Productions http://michaelgogins.tumblr.com Michael dot Gogins at gmail dot com On Fri, Jun 21, 2013 at 11:13 AM, Andres Cabrera <mantaraya36@gmail.com> wrote:
|
Date | 2013-06-21 16:26 |
From | Felipe Sateler |
Subject | Re: [Cs-dev] API naming consistency |
I'm not a user of the API, so my suggestions probably shouldn't carry much weight On Fri, Jun 21, 2013 at 11:13 AM, Andres Cabrera |
Date | 2013-06-21 17:20 |
From | Michael Gogins |
Subject | Re: [Cs-dev] API naming consistency |
Attachments | None None |
And I agree with this as well. Regards, Mike ===========================
Michael GoginsIrreducible Productions http://michaelgogins.tumblr.com Michael dot Gogins at gmail dot com On Fri, Jun 21, 2013 at 11:26 AM, Felipe Sateler <fsateler@gmail.com> wrote: I'm not a user of the API, so my suggestions probably shouldn't carry |
Date | 2013-06-21 18:01 |
From | Victor Lazzarini |
Subject | Re: [Cs-dev] API naming consistency |
I'm happy with any names that look consistent and clear. I am not too keen on very long ones like the ones in the jni, otherwise it's OK to me. On 21 Jun 2013, at 16:13, Andres Cabrera wrote: > Hi, > > I was thinking it might be good to have more consistency in the naming of API functions. Please let me know if you agree or disagree with these changes and I can do them: > > 1)Create/Destroy pairs: > > These functions are create/destroy pairs, I think most others should follow the same pattern: > > PUBLIC CSOUND *csoundCreate(void *hostData); > PUBLIC void csoundDestroy(CSOUND *); > > PUBLIC void *csoundCreateThreadLock(void); > PUBLIC void csoundDestroyThreadLock(void *lock); > > PUBLIC void *csoundCreateMutex(int isRecursive); > PUBLIC void csoundDestroyMutex(void *mutex_); > > PUBLIC void *csoundCreateBarrier(unsigned int max); > PUBLIC int csoundDestroyBarrier(void *barrier); > > PUBLIC int csoundCreateGlobalVariable(CSOUND *, > PUBLIC int csoundDestroyGlobalVariable(CSOUND *, const char *name); > > > Creates without paired Destroys: > > I think Destroy should be used instead of Free: > > PUBLIC void *csoundCreateCircularBuffer(CSOUND *csound, int size); > PUBLIC void csoundFreeCircularBuffer(CSOUND *csound, void *circularbuffer); > > Destroy without Create: > > I think Create should be used instead of Enable: > > PUBLIC void csoundEnableMessageBuffer(CSOUND *csound, int toStdOut); > void PUBLIC csoundDestroyMessageBuffer(CSOUND *csound); > > Different: > > Not sure what to do about these, maybe they should stay as they are: > PUBLIC int csoundNewOpcodeList(CSOUND *, opcodeListEntry **opcodelist); > PUBLIC void csoundDisposeOpcodeList(CSOUND *, opcodeListEntry *opcodelist); > > These are probably OK: > PUBLIC void csoundDeleteTree(CSOUND *csound, TREE *tree); > PUBLIC void csoundDeleteChannelList(CSOUND *, controlChannelInfo_t *lst); > PUBLIC void csoundDeleteUtilityList(CSOUND *, char **lst); > > PUBLIC void *csoundCreateThread(uintptr_t (*threadRoutine)(void *), > PUBLIC uintptr_t csoundJoinThread(void *thread); > (There is no need for DestroyThread, right?) > > 2) Dev list function names > > csoundMIDIDevList > should be changed to: > csoundGetMIDIDevList > > csoundAudioDevList > should be changed to: > csoundGetAudioDevList > > 3) Callback setters: > > I think "Register" is better than "Set" but maybe since there is only one "Register" change this one to "Set". Additionally there is one "generic" callback setter that can only set one callback, so make this an explicit and definite callbakc setter: > > Callbacks: > > PUBLIC void csoundSetFileOpenCallback(CSOUND *p, > PUBLIC void csoundSetPlayopenCallback(CSOUND *, > PUBLIC void csoundSetRtplayCallback(CSOUND *, > PUBLIC void csoundSetRecopenCallback(CSOUND *, > PUBLIC void csoundSetRtrecordCallback(CSOUND *, > PUBLIC void csoundSetRtcloseCallback(CSOUND *, void (*rtclose__)(CSOUND *)); > PUBLIC void csoundSetAudioDeviceListCallback(CSOUND *csound, > PUBLIC void csoundSetExternalMidiInOpenCallback(CSOUND *, > PUBLIC void csoundSetExternalMidiReadCallback(CSOUND *, > PUBLIC void csoundSetExternalMidiInCloseCallback(CSOUND *, > PUBLIC void csoundSetExternalMidiOutOpenCallback(CSOUND *, > PUBLIC void csoundSetExternalMidiWriteCallback(CSOUND *, > PUBLIC void csoundSetExternalMidiOutCloseCallback(CSOUND *, > PUBLIC void csoundSetExternalMidiErrorStringCallback(CSOUND *, > PUBLIC void csoundSetMIDIDeviceListCallback(CSOUND *csound, > PUBLIC void csoundSetCscoreCallback(CSOUND *, > void (*cscoreCallback_)(CSOUND *)); > PUBLIC void csoundSetDefaultMessageCallback( > void (*csoundMessageCallback_)(CSOUND *, > PUBLIC void csoundSetMessageCallback(CSOUND *, > void (*csoundMessageCallback_)(CSOUND *, > csoundSetInputChannelCallback(CSOUND *csound, > channelCallback_t inputChannelCalback); > csoundSetOutputChannelCallback(CSOUND *csound, > channelCallback_t outputChannelCalback); > PUBLIC int csoundRegisterSenseEventCallback(CSOUND *, > PUBLIC int csoundSetCallback(CSOUND *, int (*func)(void *userData, void *p, > PUBLIC void csoundRemoveCallback(CSOUND *, > PUBLIC void csoundSetMakeGraphCallback(CSOUND *, > void (*makeGraphCallback_)(CSOUND *, > PUBLIC void csoundSetDrawGraphCallback(CSOUND *, > void (*drawGraphCallback_)(CSOUND *, > PUBLIC void csoundSetKillGraphCallback(CSOUND *, > void (*killGraphCallback_)(CSOUND *, > PUBLIC void csoundSetExitGraphCallback(CSOUND *, > int (*exitGraphCallback_)(CSOUND *)); > PUBLIC void csoundSetYieldCallback(CSOUND *, int (*yieldCallback_)(CSOUND *)); > PUBLIC void csoundSetInputValueCallback(CSOUND *, > PUBLIC void csoundSetOutputValueCallback(CSOUND *, > PUBLIC void csoundSetChannelIOCallback(CSOUND *, > CsoundChannelIOCallback_t func); > > 4) For consistency should all typedef names be changed to uppercase? or all to lower case ending in "_t"? > > Cheers, > Andrés > ------------------------------------------------------------------------------ > This SF.net email is sponsored by Windows: > > Build for Windows Store. > > http://p.sf.net/sfu/windows-dev2dev_______________________________________________ > Csound-devel mailing list > Csound-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/csound-devel Dr Victor Lazzarini Senior Lecturer Dept. of Music NUI Maynooth Ireland tel.: +353 1 708 3545 Victor dot Lazzarini AT nuim dot ie ------------------------------------------------------------------------------ This SF.net email is sponsored by Windows: Build for Windows Store. http://p.sf.net/sfu/windows-dev2dev _______________________________________________ Csound-devel mailing list Csound-devel@lists.sourceforge.net |
Date | 2013-06-21 18:02 |
From | Victor Lazzarini |
Subject | Re: [Cs-dev] API naming consistency |
In some cases, yes. On 21 Jun 2013, at 16:26, Felipe Sateler wrote: > Can multpile callbacks be set? If so, I find Register to be clearer than Set. Dr Victor Lazzarini Senior Lecturer Dept. of Music NUI Maynooth Ireland tel.: +353 1 708 3545 Victor dot Lazzarini AT nuim dot ie ------------------------------------------------------------------------------ This SF.net email is sponsored by Windows: Build for Windows Store. http://p.sf.net/sfu/windows-dev2dev _______________________________________________ Csound-devel mailing list Csound-devel@lists.sourceforge.net |
Date | 2013-06-21 21:08 |
From | Andres Cabrera |
Subject | Re: [Cs-dev] API naming consistency |
Attachments | None None |
OK, I've committed the changes. I've held back on the type names and made these in a separate branch called variable_names. Let me know what you think. Cheers, Andrés On Fri, Jun 21, 2013 at 10:02 AM, Victor Lazzarini <Victor.Lazzarini@nuim.ie> wrote: In some cases, yes. |
Date | 2013-06-21 21:16 |
From | Michael Gogins |
Subject | Re: [Cs-dev] API naming consistency |
Attachments | None None |
Did you update the low-level C++ interface as well? I.e., csound.hpp? =========================== Michael GoginsIrreducible Productions http://michaelgogins.tumblr.com Michael dot Gogins at gmail dot com On Fri, Jun 21, 2013 at 4:08 PM, Andres Cabrera <mantaraya36@gmail.com> wrote:
|
Date | 2013-06-21 22:00 |
From | Victor Lazzarini |
Subject | Re: [Cs-dev] API naming consistency |
Attachments | None None |
Does the Android and iOS code need to change too? Victor On 21 Jun 2013, at 21:08, Andres Cabrera wrote:
Dr Victor Lazzarini Senior Lecturer Dept. of Music NUI Maynooth Ireland tel.: +353 1 708 3545 Victor dot Lazzarini AT nuim dot ie |
Date | 2013-06-21 22:40 |
From | Michael Gogins |
Subject | Re: [Cs-dev] API naming consistency |
Attachments | None None |
I would think so, i'll do the Android code. On Jun 21, 2013 5:00 PM, "Victor Lazzarini" <Victor.Lazzarini@nuim.ie> wrote:
|
Date | 2013-06-21 22:44 |
From | jpff@cs.bath.ac.uk |
Subject | Re: [Cs-dev] API naming consistency |
Late but....I dislike long names as they make laying out code difficult; I use 85 char-wide screens so I can read the text. ------------------------------------------------------------------------------ This SF.net email is sponsored by Windows: Build for Windows Store. http://p.sf.net/sfu/windows-dev2dev _______________________________________________ Csound-devel mailing list Csound-devel@lists.sourceforge.net |
Date | 2013-06-22 01:45 |
From | Andres Cabrera |
Subject | Re: [Cs-dev] API naming consistency |
Attachments | None None |
I think I have done all the necessary changes to the C++ and the Android and iOS sources. The changes to long names, I haven't pushed to the master branch but to a separate branch, in case there's disagreement.Cheers, Andrés On Fri, Jun 21, 2013 at 2:40 PM, Michael Gogins <michael.gogins@gmail.com> wrote:
|