【问题标题】:Java threading JavaDocJava 线程 JavaDoc
【发布时间】:2010-09-23 11:48:37
【问题描述】:

我写了一个只应该在特定线程上调用的方法。是否应将标准注释或注释添加到方法的 javadoc 中以表示这一点?

【问题讨论】:

    标签: java multithreading thread-safety javadoc


    【解决方案1】:

    不知道有任何此类标准注释。 Java Concurrency in Practice 处理其第 4.5 节中的问题:记录同步策略。一些提示希望能帮助您使文档清晰有用:

    至少,记录一个类所做的线程安全保证。它是线程安全的吗?它会在持有锁的情况下进行回调吗?是否有任何特定的锁会影响其行为?不要强迫客户做出冒险的猜测。如果您不想承诺支持客户端锁定,那很好,但要这么说。如果您希望客户端能够在您的类上创建新的原子操作,就像我们在 4.4 节中所做的那样,您需要记录他们应该获取哪些锁才能安全地执行此操作。如果您使用锁来保护状态,请将其记录下来以供将来的维护者使用,因为它非常简单 - @GuardedBy 注释可以解决问题。如果您使用更微妙的方式来维护线程安全,请将它们记录下来,因为它们对维护者来说可能并不明显。

    他们还使用了一些注释,这些注释不是标准的,但由他们推荐(参见附录 A)。但是,对于方法,他们只提供@GuardedBy 的变体,这不适用于您的情况。

    我建议在纯 Javadoc 中清楚地记录需求。

    【讨论】:

      【解决方案2】:

      在我看来,处理它的最佳方法是删除该要求。将方法更改为私有并通过添加单词Workload 或Internal 或其他内容来稍微重命名它。然后创建一个具有相同签名的新公共方法。让这个方法检查你是否在正确的线程上。如果你是,你可以只执行私有方法。如果不是,则安排私有方法在正确的线程上执行。这样,API 的用户就不必担心线程,只需调用方法即可。

      然后,在 javadoc 中没有什么可指定的,尽管在公共和私有方法的描述中包含这些信息仍然很有用。

      当我需要在 EDT 上执行某些操作时,这是我使用的模式:

      /** * 使用指定的疯狂参数在 EDT 上执行某些操作。如果这是 * 在 EDT 之外调用,它将安排在 EDT 上完成的工作 * 尽早。该方法的实际工作见 * {@link #executeSomethingInternal(int)}。 * * @argument crazyArgument 一些疯狂的论点 */ public void executeSomething(int crazyArgument) { 如果(SwingUtilities.isEventDispatchThread()){ this.executeSomethingInternal(crazyArgument); } 别的 { 可运行 r = new Runnable() { 私人 int crazyArgument; 公共可运行 setCrazyArgument(int crazyArgument) { this.crazyArgument = crazyArgument; 返回这个; } @覆盖 公共无效运行(){ this.OuterClass.executeSomethingInternal(this.crazyArgument); } }.setCrazyArgument(crazyArgument); SwingUtilities.invokeLater(r); } } /** * 这种方法确实有效。这个类保证 * 总是在 EDT 上被调用。此 API 的用户应调用 * {@link #executeSomething(int)}。 */ 私人无效executeSomethingInternal(int crazyArgument){ // 在这里工作 }

      【讨论】:

      • 要真正深入人心,您可能还想在executeSomethingInternal 方法中使用断言,例如assert SwingUtilities.isEventDispatchThread()
      • 作为私有方法,executeSomethingInternal 只能在同一个类中调用。如果所有调用都在executeSomething 中,那么就不可能在 EDT 之外调用executeSomethingInternal。该断言将确保未来的程序员不会故意或不考虑设计而违反此规定。
      • 不幸的是,即使是私有方法也需要文档。
      • @Alison:删除只能在 EDT 上运行的要求,而不是删除文档要求。如您所见,我实际上在示例代码中包含了文档。
      猜你喜欢
      • 2011-05-10
      • 2011-03-07
      • 2017-08-31
      • 1970-01-01
      • 2011-03-11
      • 1970-01-01
      • 1970-01-01
      • 1970-01-01
      • 2011-11-05
      相关资源
      最近更新 更多