Why include methods in a public API like Thread.destroy() that aren't implemented?

I'm a bit puzzled by this one. There are some methods in the 开发者_Python百科Java API like Thread.destroy() that aren't implemented at all. (I know it hasn't been implemented probably because it would be deadlock prone, but that's not what I'm getting at.) If it's not implemented, then why even include it in the public API? It's just a useless method that people could call to cause an exception at runtime.

I can see the point in this sort of thing when you're implementing an interface and a particular implementation doesn't implement all the methods for one reason or another. But that isn't the case with thread.

The only thing I can think of is that it was a design decision taken by Java devs in the early days to show what features planned to be in place - and obviously with the discoveries of the thread issues it never paid off. But that's a wild guess and it seems a bit of a silly one.

Can anyone else shed some light on this one?

Following on from this, since it's not implemented why don't they remove it? I know there's the whole thing with Java backwards compatibility, but since there's no code that could possibly call this method and ever work at runtime, surely it's not a code-breaking change? Or does the fact it could compile before and can't now count (even though it couldn't compile to anything meaningful?)

Edit: As of Java 11, it is indeed removed.

The documentation for Thread.destroy() links to reasons for deprecation of Thread's methods. Curiously, the link states:

We are not implementing it at this time, but neither are we deprecating it

even though method is clearly annotated as deprecated. It is as if they included it in the API, so people could call it and expect the designed functionality to work later, then thought better of it, so they included the note saying "Not implemented, but not deprecated", then just went ahead and deprecated it, and forgot to update the documentation.

Oracle does take bug reports, perhaps this qualifies for feedback they could use to enhance their documentation.

Have you read the docs for it?

This method was originally designed to destroy this thread without any cleanup. Any monitors it held would have remained locked. However, the method was never implemented. If if were to be implemented, it would be deadlock-prone in much the manner of suspend(). If the target thread held a lock protecting a critical system resource when it was destroyed, no thread could ever access this resource again. If another thread ever attempted to lock this resource, deadlock would result. Such deadlocks typically manifest themselves as "frozen" processes. For more information, see Why are Thread.stop, Thread.suspend and Thread.resume Deprecated?.

Also, from "Java Thread Primitive Deprecation" (linked from above):

Thread.destroy has never been implemented. If it were implemented, it would be deadlock-prone in the manner of Thread.suspend. (In fact, it is roughly equivalent to Thread.suspend without the possibility of a subsequent Thread.resume.) We are not implementing it at this time, but neither are we deprecating it (forestalling its implementation in future). While it would certainly be deadlock prone, it has been argued that there may be circumstances where a program is willing to risk a deadlock rather than exit outright.