Value Members

1.  val LedgerCommandId: daml.lf.data.Ref.CommandId.type
2.  val LedgerParticipantId: ParticipantId.type
3.  val LedgerSubmissionId: SubmissionId.type
4.  val LedgerTransactionId: TransactionId.type
5.  val LedgerUserId: daml.lf.data.Ref.UserId.type
6.  val LfChoiceName: ChoiceName.type
7.  val LfCommand: ReplayCommand.type
8.  val LfCommandId: daml.lf.data.Ref.CommandId.type
9.  val LfCreateCommand: Create.type
10.  val LfExerciseByKeyCommand: ExerciseByKey.type
11.  val LfExerciseCommand: Exercise.type
12.  val LfFetchByKeyCommand: FetchByKey.type
13.  val LfFetchCommand: Fetch.type
14.  val LfInterfaceId: TypeConName.type
15.  val LfLedgerString: LedgerString.type
16.  val LfLookupByKeyCommand: LookupByKey.type
17.  val LfPackageId: PackageId.type
18.  val LfPackageName: PackageName.type
19.  val LfPackageRef: PackageRef.type
20.  val LfPackageVersion: PackageVersion.type
21.  val LfPartyId: Party.type
22.  val LfSubmissionId: SubmissionId.type
23.  val LfTimestamp: Timestamp.type
24.  val LfValue: Value.type
25.  val LfVersioned: Versioned.type
26.  val LfWorkflowId: daml.lf.data.Ref.WorkflowId.type
27.  val SequencerCounter: CounterCompanion[SequencerCounterDiscriminator]
28.  def checked[A](x: => A): A

    Wrap a method call with this method to document that the caller is sure that the callee's preconditions are met.

29.  def checkedToByteString(proto: GeneratedMessage): ByteString

    We should not call toByteString directly on a proto message.

    We should not call toByteString directly on a proto message. Rather, we should use the versioning tooling which ensures that the correct version of the proto message is used (based on the protocol version). However, in some cases (e.g., when we are sure that the message is not versioned), we can invoke this method directly.

    Annotations

    @SuppressWarnings()

30.  implicit val lfPartyOrdering: Ordering[LfPartyId]
31.  object CantonAppDriver
32.  object CantonCommunityApp extends CantonAppDriver
33.  object CantonEnterpriseApp extends CantonAppDriver
34.  object CommandId extends Serializable
35.  object ConsoleScriptRunner extends NoTracing
36.  object DirectGrpcServiceInvocation extends WartTraverser

    This wart warns when methods for a gRPC service stub are called directly.

    This wart warns when methods for a gRPC service stub are called directly. Instead, the wrapper methods from CantonGrpcUtil and others should be used. This ensures in particular the following aspects:

    • The current trace context is set in the gRPC context prior to the call so that the gRPC stub implementation picks it up.
    • Error handling is done consistently across gRPC calls.

    Such helper methods are annotated @GrpcServiceInvocationMethod. The wart does not check any arguments at any call site, nor the implementation of such a method or any of its overrides. It is the responsibility of the developer to ensure that typical usage patterns of this method are safe w.r.t. the above aspects. Primary constructors can be annotated via their class.

    For example, instead of myServiceStub.myMethod(request), you should use CantonGrpcUtil.sendGrpcRequest(myServiceStub, ...)(_.myMethod(request)).

37.  object DiscardedFuture extends WartTraverser

    Flags statements that return a scala.concurrent.Future.

    Flags statements that return a scala.concurrent.Future. Typically, we should not discard scala.concurrent.Future because exceptions inside the future may not get logged. Use FutureUtil.doNotAwait to log exceptions and discard the future where necessary.

    Also detects discarded cats.data.EitherT[scala.concurrent.Future, ..., ...] and cats.data.OptionT[scala.concurrent.Future, ...] and arbitrary nestings of those. Custom type constructors can be registered to take the same role as scala.concurrent.Future by annotating the type definition with DoNotDiscardLikeFuture.

    Also flags usages of scala.collection.IterableOnceOps.foreach and scala.collection.IterableOnceOps.tapEach where the function returns a future-like type.

    This wart is a special case of the warts NonUnitStatements and NonUnitForEach and scalac's -Wnonunit-statement flag, in that it warns only if the return type is future-like. Additionally, this wart uses a different set of exceptions when no warning is issued. We keep this specialized wart for two reasons:

    1. It is not practically feasible to use -Wnonunit-statement and NonUnitForEach in scalatest because it would flag many of the assertions of the form x should be >= y in statement positions. Yet, it is important to check for discarded futures in tests because a discarded future may hide an exception.
    2. In some production code, it is convenient to suppress the warnings coming from -Wnonunit-statement and NonUnitForEach, just due to how the code is written. In such places, we still want to benefit from the explicit checks against discarded futures.

    This wart does not look at futures that are discarded at the end of a unit-type expression. These cases are caught by -Ywarn-value-discard. We do not implement a specialized version for future-like values because we do not expect to suppress the warnings coming from -Ywarn-value-discard.

38.  object EnforceVisibleForTesting extends WartTraverser

    Wart such that we avoid using vals, defs, objects, classes, etc...

    Wart such that we avoid using vals, defs, objects, classes, etc... that are marked with com.google.common.annotations.VisibleForTesting in production code.

    Notice that usage of such definitions is allowed in the private or protected scope.

39.  object FutureAndThen extends WartTraverser

    Wart such that we avoid using scala.concurrent.Future.andThen

    Wart such that we avoid using scala.concurrent.Future.andThen

    Using scala.concurrent.Future.andThen seems to be a bad idea because it swallows the exceptions in the andThen part.

    Better use our own implementation in Thereafter.

40.  object FutureLikeTester
41.  object FutureTraverse extends WartTraverser

    Cats' traverse and sequence methods do not specify the evaluation behaviour and this behaviour has changed between minor versions (e.g., 2.6 and 2.7).

    Cats' traverse and sequence methods do not specify the evaluation behaviour and this behaviour has changed between minor versions (e.g., 2.6 and 2.7). When we traverse over containers, we should therefore be explicit whether the traversal is parallel or sequential. This wart flags all usages of Cats' syntax extensions for future-like applicatives, except when used with the singleton containers scala.Option and scala.Either.

    Limitations:

    • It does not flag traverse calls whose applicative instance is more general and can be instantiated with a future-like instance.
42.  object GlobalExecutionContext extends WartTraverser

    The global execution context scala.concurrent.ExecutionContext.global should be avoided because it is integrated with neither of the following:

    The global execution context scala.concurrent.ExecutionContext.global should be avoided because it is integrated with neither of the following:

    • Canton's error reporting
    • execution context supervision
    • thread count configuration
    • the workarounds for the bugs in the ForkJoinPool Moreover, if it is used in tests, the tests may interfere in unexpected ways.

    For unit tests, mix in the traits com.daml.resources.HasExecutionContext or com.digitalasset.canton.HasExecutorService, which provide a suitably configured scala.concurrent.ExecutionContext. For integration tests, an execution context should already be in scope. In production code, properly pass the right scala.concurrent.ExecutionContext into where it is needed. Create a new one using com.digitalasset.canton.concurrent.Threading if absolutely necessary.

    For similar reasons, the scala.concurrent.ExecutionContext.parasitic should not be used. Use com.digitalasset.canton.concurrent.DirectExecutionContext instead.

    scala.concurrent.ExecutionContext.opportunistic should be avoided as well, but given that scala.concurrent.ExecutionContext.opportunistic is private to the scala package, this wart does not check for it.

43.  object NonUnitForEach extends WartTraverser

    This wart warns when methods scala.collection.IterableOnceOps.foreach and scala.collection.IterableOnceOps.tapEach are used with non-unit valued functions.

    This wart warns when methods scala.collection.IterableOnceOps.foreach and scala.collection.IterableOnceOps.tapEach are used with non-unit valued functions. This is needed because these methods' signature accepts any-valued functions. So -Ywarn-value-discard does not warn about such discarded values.

    scala.collection.IterableOnceOps.foreach is also used in for loops without yield and therefore also covers cases such as for { x <- 1 to 10 } { x + 5 }.

    Builder operations such as b += ... are identified by their return type this.type and ignored when checking for non-unit return values. This allows common usages such as for { x <- 1 to 10 } { b += x } and for { x <- 1 to 10 } { if (x % 2 == 0) b += x }. This does not work for all usages though; you can force a Unit type by specifying the type argument of scala.collection.IterableOnceOps.foreach and scala.collection.IterableOnceOps.tapEach as in (1 to 10).foreach[Unit] { ... }, or by ascribing Unit as in (1 to 10).foreach { x => f(x): Unit }, or by explicitly discarding the result: (1 to 10).foreach { x => f(x).discard }.

44.  object ProtoDeserializationError extends ProtoDeserializationErrorGroup with Serializable
45.  object ProtobufToByteString extends WartTraverser

    Detects calls to toByteString on generated protobuf messages.

    Detects calls to toByteString on generated protobuf messages.

    See also

    https://github.com/DACH-NY/canton/blob/main/contributing/backwards-incompatible-changes.md

46.  object ReassignmentCounter extends CounterCompanion[ReassignmentDiscriminator]
47.  object RepairCounter extends CounterCompanion[RepairCounterDiscriminator]
48.  object RequestCounter extends CounterCompanion[RequestCounterDiscriminator]
49.  object RequireBlocking extends WartTraverser

    All blocking method calls should be wrapped in scala.concurrent.blocking so that the execution context knows that it may have to spawn a new process.

    All blocking method calls should be wrapped in scala.concurrent.blocking so that the execution context knows that it may have to spawn a new process.

    This wart checks that all @{code synchronized} calls are surrounded immediately by a scala.concurrent.blocking call. It also complains about calls to java.lang.Thread.sleep as Threading.sleep should be used instead.

    The logic can currently be fooled by renaming synchronized and sleep.

50.  object SequencerAlias extends LengthLimitedStringWrapperCompanion[String255, SequencerAlias] with Serializable
51.  object SynchronizedFuture extends WartTraverser

    When a synchronized block returns a scala.concurrent.Future, then the synchronization typically does not extend to the computations performed inside the future.

    When a synchronized block returns a scala.concurrent.Future, then the synchronization typically does not extend to the computations performed inside the future. This often hides a concurrency bug that is hard to spot during review because the computation's code is lexically inside the synchronized block and it may not be obvious that scala.concurrent.Futures are in play.

    For example, synchronized blocks are often used to read and update the state of an object atomically. When the update operation involves a scala.concurrent.Future like below, then the write to the state is actually not guarded by the synchronized call and the update is not atomic.

    synchronized {
      val x = this.atomicRef.get()
      futureComputation(x).map { y =>
        this.atomicRef.set(y)
        y
      }
    }

    The proper approach in the above example is to use a semaphore instead of a synchronized block.

    blocking { this.semaphore.acquire() }
    val x = this.atomicRef.get()
    futureComputation(x).map { y =>
      this.atomicRef.set(y)
      y
    }.thereafter { _ => this.semaphore.release() }

    If the synchronization intentionally does not have to extend over the scala.concurrent.Future computation, it usually helps with readability to move the future out of the synchronized block. For example,

    blocking(synchronized {
      val x = criticalSection()
      Future { nonCriticalSection(x) }
    })

    should be written as follows:

    val x = blocking(synchronized { criticalSection() })
    Future { nonCriticalSection(x) }

    There are cases where the synchronized block is supposed to return a scala.concurrent.Future, for example when dealing with the promise of a future. In such a case, the warning should simply be suppressed locally.

52.  object SynchronizerAlias extends LengthLimitedStringWrapperCompanion[String255, SynchronizerAlias] with Serializable
53.  object TryFailed extends WartTraverser

    Wart such that we avoid using Try.failed

    Wart such that we avoid using Try.failed

    Using Try.failed seems to be a bad idea because it will create an UnsupportedOperationException for each Success, which constantly builds a stack trace and then throws it away. Seems to be quite expensive in particular in tight loops.

    Better match on a Try. If you need failed.foreach, use TryUtil.forFailed instead.

54.  object UserId extends Serializable
55.  object WorkflowId extends Serializable