Java threading JavaDoc

Question

Ich habe eine Methode geschrieben, die nur für einen bestimmten Thread aufgerufen werden sollte. Gibt es eine Standard-Anmerkung oder Notiz, die dem Javadoc der Methode hinzugefügt werden sollte, um dies zu bezeichnen?

Answer 1

Ich kenne keine solchen Standard-Annotationen. Java Concurrency in Practice befasst sich mit der Frage in Abschnitt 4.5: Dokumentieren von Synchronisierungsrichtlinien. Ein paar Tipps, die Ihnen hoffentlich helfen, Ihre Dokumentation klar und nützlich zu machen:

Dokumentieren Sie zumindest die Thread-Sicherheitsgarantien einer Klasse. Ist es threadsicher? Werden Callbacks mit einer Sperre durchgeführt? Gibt es bestimmte Sperren, die das Verhalten beeinflussen? Zwingen Sie die Kunden nicht zu riskanten Vermutungen. Wenn Sie sich nicht zur Unterstützung der clientseitigen Sperrung verpflichten möchten, ist das in Ordnung, aber sagen Sie es. Wenn Sie möchten, dass Clients in der Lage sind, neue atomare Operationen in Ihrer Klasse zu erstellen, wie in Abschnitt 4.4, müssen Sie dokumentieren, welche Sperren sie benötigen, um dies sicher zu tun. Wenn Sie Sperren verwenden, um den Status zu schützen, dokumentieren Sie dies für zukünftige Administratoren, da dies so einfach ist - die @GuardedBy Annotation wird den Trick machen. Wenn Sie subtilere Mittel zur Aufrechterhaltung der Thread-Sicherheit verwenden, dokumentieren Sie sie, da sie für die Betreuer möglicherweise nicht offensichtlich sind.

Sie verwenden auch einige Anmerkungen, die nicht Standard sind, aber von ihnen empfohlen werden (siehe Anhang A). Für Methoden bieten sie jedoch nur Variationen von @GuardedBy, die für Ihren Fall nicht anwendbar ist.

Ich empfehle nur klar die Anforderung in einfachen Javadoc zu dokumentieren.

Answer 2

Meiner Meinung nach ist der beste Weg, damit umzugehen, die Anforderung zu entfernen. Ändern Sie die Methode in private und benennen Sie sie leicht um, indem Sie das Wort Workload oder Internal oder etwas hinzufügen. Erstellen Sie dann eine neue öffentliche Methode mit derselben Signatur. Lassen Sie diese Methode überprüfen, um zu sehen, ob Sie im richtigen Thread sind. Wenn dies der Fall ist, können Sie einfach die private Methode ausführen. Wenn nicht, dann planen Sie die private Methode, die im richtigen Thread ausgeführt werden soll. Auf diese Weise muss sich der Benutzer der API nicht um das Threading kümmern und kann die Methode nur aufrufen.

Dann gibt es nichts im Javadoc zu spezifizieren, obwohl es immer noch nützlich ist, diese Informationen in die Beschreibung der öffentlichen und privaten Methoden aufzunehmen.

Dies ist das Muster, das ich benutze, wenn ich etwas auf dem EDT ausgeführt müssen:

 
/** 
* 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 
}