Java threading JavaDoc

Question

Ho scritto un metodo che dovrebbe essere chiamato solo su un thread particolare. C'è un'annotazione o una nota standard che dovrebbe essere aggiunta al metodo javadoc per denotare questo?

Answer 1

Non so di tali annotazioni standard. Java Concurrency in Practice tratta la domanda nella sua sezione 4.5: Documentazione dei criteri di sincronizzazione. Alcuni suggerimenti che ti aiuteranno a rendere la tua documentazione chiara e utile:

Per lo meno, documenta le garanzie di sicurezza del filo fatte da una classe. È thread-safe? Rende i callback con un blocco trattenuto? Ci sono dei blocchi specifici che influenzano il suo comportamento? Non forzare i clienti a fare ipotesi azzardate. Se non vuoi impegnarti a supportare il blocco sul lato client, va bene, ma dillo. Se vuoi che i client siano in grado di creare nuove operazioni atomiche sulla tua classe, come abbiamo fatto nella Sezione 4.4, devi documentare quali lock dovrebbero acquisire per farlo in modo sicuro. Se si utilizzano i blocchi sullo stato di protezione, documentarlo per i futuri manutentori, perché è così semplice: l'annotazione @GuardedBy farà il trucco. Se si utilizzano metodi più sottili per mantenere la sicurezza dei thread, documentarli perché potrebbero non essere ovvi per i manutentori.

Si utilizzano anche alcune annotazioni, che non sono standard, ma raccomandate da loro (vedere Appendice A). Tuttavia, per i metodi offrono solo variazioni di @GuardedBy, che non è applicabile al tuo caso.

Si consiglia di documentare chiaramente il requisito in plain Javadoc.

Answer 2

A mio parere, il modo migliore per gestirlo è rimuovere il requisito. Cambia il metodo in privato e rinominalo leggermente aggiungendo la parola Workload o Internal o qualcosa del genere. Quindi creare un nuovo metodo pubblico con la stessa firma. Verifica questo metodo per vedere se sei nella discussione corretta. Se lo sei, puoi semplicemente eseguire il metodo privato. In caso contrario, pianificare il metodo privato da eseguire sul thread corretto. In questo modo, l'utente dell'API non deve preoccuparsi del threading e può semplicemente chiamare il metodo.

Quindi, non c'è nulla da specificare in javadoc, sebbene sia ancora utile includere queste informazioni nella descrizione dei metodi pubblici e privati.

Questo è il modello che uso quando ho bisogno di qualcosa eseguito sul EDT:

 
/** 
* Executes something on the EDT with the crazy argument specified. If this is 
* called outside of the EDT, it will schedule the work to be done on the EDT 
* as soon as possible. The actual work of this method is found in 
* {@link #executeSomethingInternal(int)}. 
* 
* @argument crazyArgument some crazy argument 
*/ 
public void executeSomething(int crazyArgument) { 
    if (SwingUtilities.isEventDispatchThread()) { 
    this.executeSomethingInternal(crazyArgument); 
    } else { 
    Runnable r = new Runnable() { 
     private int crazyArgument; 

     public Runnable setCrazyArgument(int crazyArgument) { 
     this.crazyArgument = crazyArgument; 
     return this; 
     } 

     @Override 
     public void run() { 
     this.OuterClass.executeSomethingInternal(this.crazyArgument); 
     } 
    }.setCrazyArgument(crazyArgument); 
    SwingUtilities.invokeLater(r); 
    } 
} 

/** 
* This method actually does the work. It is guaranteed by this class to 
* always get called on the EDT. Users of this API should call 
* {@link #executeSomething(int)}. 
*/ 

private void executeSomethingInternal(int crazyArgument) { 
    // do work here 
}