[Tcl-bugs] [ tcl-Bugs-547989 ] Undocumented public API: threads

[SourceForge.net <no...@so...>]

Bugs item #547989, was opened at 2002-04-24 10:57
Message generated for change (Comment added) made by dkf
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=110894&aid=547989&group_id=10894

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: 48. Threading
Group: obsolete: 8.4a5
Status: Open
Resolution: None
>Priority: 7
Private: No
Submitted By: Donal K. Fellows (dkf)
Assigned to: Zoran Vasiljevic (vasiljevic)
Summary: Undocumented public API: threads

Initial Comment:
The following publically-named API functions are
undocumented.

Tcl_GetAllocMutex (mac/tclMacThrd.c)
Tcl_GetAllocMutex (unix/tclUnixThrd.c)
Tcl_GetAllocMutex (win/tclWinThrd.c)


----------------------------------------------------------------------

>Comment By: Donal K. Fellows (dkf)
Date: 2008-03-20 10:00

Message:
Logged In: YES 
user_id=79902
Originator: YES

It seems to me that the right thing to do is to switch this to a call in
the internal stubs table; anything poking this deep needs to beware the
dragons anyway. Hence it is better not documented (other than perhaps in
comments in tclInt.decls and the rest of the sources).

Dropping prio; no way should this block the 8.5.2 release!

----------------------------------------------------------------------

Comment By: Donal K. Fellows (dkf)
Date: 2007-12-13 11:49

Message:
Logged In: YES 
user_id=79902
Originator: YES

Looking in the 'changes' file, I see this:

8/9/99 (internal api change) Removed the TclpMutexLock and
TclpMutexUnlock
APIs and added a new exported api, Tcl_GetAllocMutex. These APIs are all
for
the mutex used in the simple memory allocators.  By making this change
we are able to substitute different implementations of the thread-related
APIs without having to recompile the Tcl core. (welch)


----------------------------------------------------------------------

Comment By: Zoran Vasiljevic (vasiljevic)
Date: 2007-06-30 20:30

Message:
Logged In: YES 
user_id=95086
Originator: NO

All is clear.

----------------------------------------------------------------------

Comment By: Donal K. Fellows (dkf)
Date: 2007-06-30 19:04

Message:
Logged In: YES 
user_id=79902
Originator: YES

I agree (given comments here) that it probably should be called
TclpGetAllocMutex, and should have MODULE_SCOPE, but who knows who is
calling it? :-( So, I suggest doing the rename and then creating a wrapper
function (called Tcl_GetAllocMutex) that calls the real function. (Maybe
while printing a message stderr that an unsupported/deprecated API has been
called?) There should also be a comment in tcl.decls beside the function
declaration that indicates that the function is deprecated and likely to be
removed in 9.0.

With that done, open a separate FRQ ticket to remind us to revisit this
(i.e. remove the function) for 9.0, which is when we allow that sort of ABI
change. With *that* done, close this ticket.

Does this make things clear?

----------------------------------------------------------------------

Comment By: Zoran Vasiljevic (vasiljevic)
Date: 2007-06-30 16:59

Message:
Logged In: YES 
user_id=95086
Originator: NO

I have very little experience with stub exported calls.
It is definitely so that above are to be used only internally
and should therefore be named as TclpGetAllocMutex or such.
They should not be exported.  

So what to do? Wait for 9.0 and scrap them out of the 
public API?

----------------------------------------------------------------------

Comment By: Andreas Kupries (andreas_kupries)
Date: 2002-05-14 20:15

Message:
Logged In: YES 
user_id=75003

It is also exported through the public stub table.

Its description however indicates that it is more
an internal function required for the initialization
of the memory allocation subsystem (MAS) of the
core.

IMHO making it public makes sense only if we allow
the replacement of the MAS by an external system.
Something I consider unlikely.

Hm, ports to PDA's ? ... No, not even for such.
They most likely will use a different allocator,
yes, but that is part of the porting work. The
change is not externally visible.

So, my recommendation for now is to not to
document this function and to make it internal
in the next major release of the core.

I will assign this now to Jeff to get his
opinion too.


----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=110894&aid=547989&group_id=10894