Java threading JavaDoc

Question

He escrito un método que solo debe invocarse en un hilo en particular. ¿Hay una anotación o nota estándar que se debería agregar al javadoc del método para denotar esto?

Answer 1

No conozco ninguna de estas anotaciones estándar. Java Concurrency in Practice trata la pregunta en su sección 4.5: Documentando las Políticas de Sincronización. Unos consejos que esperamos ayudarle a hacer su documentación clara y útil:

Por lo menos, documentan las garantías de seguridad de hilo hechas por una clase. ¿Es seguro para subprocesos? ¿Realiza devoluciones de llamada con un bloqueo? ¿Hay bloqueos específicos que afectan su comportamiento? No obligue a los clientes a hacer conjeturas arriesgadas. Si no quiere comprometerse a mantener el bloqueo del lado del cliente, está bien, pero dígalo. Si desea que los clientes puedan crear nuevas operaciones atómicas en su clase, como hicimos en la Sección 4.4, necesita documentar qué cerraduras deben adquirir para hacerlo de manera segura. Si usa bloqueos para proteger el estado, documente esto para los mantenedores futuros, porque es muy fácil: la anotación @GuardedBy hará el truco. Si usa medios más sutiles para mantener la seguridad del hilo, documentarlos porque pueden no ser obvios para los mantenedores.

También utilizan algunas anotaciones, que no son estándar, pero que recomiendan (consulte el Apéndice A). Sin embargo, para los métodos, solo ofrecen variaciones de @GuardedBy, que no se aplica a su caso.

Recomiendo simplemente documentar claramente el requisito en Javadoc simple.

Answer 2

En mi opinión, la mejor manera de manejarlo es eliminar el requisito. Cambia el método a privado y renómbralo ligeramente agregando la palabra Workload o Internal o algo así. Luego crea un nuevo método público con la misma firma. Haga que este método verifique si está en el hilo correcto. Si es así, puede ejecutar el método privado. De lo contrario, programe el método privado para que se ejecute en el hilo correcto. De esta forma, el usuario de la API no tiene que preocuparse por el subprocesamiento y puede simplemente llamar al método.

Entonces, no hay nada que especificar en el javadoc, aunque sigue siendo útil incluir esta información en la descripción de los métodos público y privado.

Este es el modelo que utilizo cuando necesito algo ejecutado en el 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 
}