Menu
I have written a method which should only be called on a particular thread. Is there a standard annotation or note which should be added to the method's javadoc to denote this?
670
Thread. currentThread() is a static method which provides reference to currently executing Thread (basically a reference to 'this' thread). Accessing non-static members (especially this ) inside a static method is not possible in Java, so currentThread() is a native method.
Threads allows a program to operate more efficiently by doing multiple things at the same time. Threads can be used to perform complicated tasks in the background without interrupting the main program.
Don't know of any such standard annotations. Java Concurrency in Practice deals with the question in its section 4.5: Documenting Synchronization Policies. A few hints which hopefully help you make your documentation clear and useful:
At the very least, document the thread safety guarantees made by a class. Is it thread-safe? Does it make callbacks with a lock held? Are there any specific locks that affect its behavior? Don't force clients to make risky guesses. If you don't want to commit to supporting client-side locking, that's fine, but say so. If you want clients to be able to create new atomic operations on your class, as we did in Section 4.4, you need to document which locks they should acquire to do so safely. If you use locks to guard state, document this for future maintainers, because it's so easy - the
@GuardedByannotation will do the trick. If you use more subtle means to maintain thread safety, document them because they may not be obvious to maintainers.
They also use some annotations, which are not standard, but recommended by them (see Appendix A). However, for methods they only offer variations of @GuardedBy, which is not applicable to your case.
I recommend just clearly documenting the requirement in plain Javadoc.
191
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
