Swift2JavaTranslator+Printing.swift

//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2024 Apple Inc. and the Swift.org project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift.org project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//

import Foundation
import SwiftBasicFormat
import SwiftParser
import SwiftSyntax

// ==== ---------------------------------------------------------------------------------------------------------------
// MARK: File writing

let PATH_SEPARATOR = "/"  // TODO: Windows

extension Swift2JavaTranslator {

  /// Every imported public type becomes a public class in its own file in Java.
  public func writeExportedJavaSources(outputDirectory: String) throws {
    var printer = CodePrinter()
    try writeExportedJavaSources(outputDirectory: outputDirectory, printer: &printer)
  }

  public func writeExportedJavaSources(outputDirectory: String, printer: inout CodePrinter) throws {
    for (_, ty) in importedTypes.sorted(by: { (lhs, rhs) in lhs.key < rhs.key }) {
      let filename = "\(ty.javaClassName).java"
      log.info("Printing contents: \(filename)")
      printImportedClass(&printer, ty)

      if let outputFile = try printer.writeContents(
        outputDirectory: outputDirectory,
        javaPackagePath: javaPackagePath,
        filename: filename
      ) {
        print("[swift-java] Generated: \(ty.javaClassName.bold).java (at \(outputFile))")
      }
    }

    do {
      let filename = "\(self.swiftModuleName).java"
      log.info("Printing contents: \(filename)")
      printModule(&printer)

      if let outputFile = try printer.writeContents(
        outputDirectory: outputDirectory,
        javaPackagePath: javaPackagePath,
        filename: filename)
      {
        print("[swift-java] Generated: \(self.swiftModuleName).java (at \(outputFile)")
      }
    }
  }

  public func writeSwiftThunkSources(outputDirectory: String) throws {
    var printer = CodePrinter()

    try writeSwiftThunkSources(outputDirectory: outputDirectory, printer: &printer)
  }

  public func writeSwiftThunkSources(outputDirectory: String, printer: inout CodePrinter) throws {
    let moduleFilenameBase = "\(self.swiftModuleName)Module+SwiftJava"
    let moduleFilename = "\(moduleFilenameBase).swift"
    do {
      log.info("Printing contents: \(moduleFilename)")

      try printGlobalSwiftThunkSources(&printer)

      if let outputFile = try printer.writeContents(
        outputDirectory: outputDirectory,
        javaPackagePath: nil,
        filename: moduleFilename)
      {
        print("[swift-java] Generated: \(moduleFilenameBase.bold).swift (at \(outputFile)")
      }
    } catch {
      log.warning("Failed to write to Swift thunks: \(moduleFilename)")
    }

    // === All types
    for (_, ty) in importedTypes.sorted(by: { (lhs, rhs) in lhs.key < rhs.key }) {
      let fileNameBase = "\(ty.swiftNominal.qualifiedName)+SwiftJava"
      let filename = "\(fileNameBase).swift"
      log.info("Printing contents: \(filename)")

      do {
        try printSwiftThunkSources(&printer, ty: ty)

        if let outputFile = try printer.writeContents(
          outputDirectory: outputDirectory,
          javaPackagePath: nil,
          filename: filename)
        {
          print("[swift-java] Generated: \(fileNameBase.bold).swift (at \(outputFile)")
        }
      } catch {
        log.warning("Failed to write to Swift thunks: \(filename)")
      }
    }
  }

  public func printGlobalSwiftThunkSources(_ printer: inout CodePrinter) throws {
    let stt = SwiftThunkTranslator(self)

    printer.print(
      """
      // Generated by swift-java

      import SwiftKitSwift
      """)

    for thunk in stt.renderGlobalThunks() {
      printer.print(thunk)
      printer.println()
    }
  }

  public func printSwiftThunkSources(_ printer: inout CodePrinter, decl: ImportedFunc) {
    let stt = SwiftThunkTranslator(self)

    for thunk in stt.render(forFunc: decl) {
      printer.print(thunk)
      printer.println()
    }
  }

  package func printSwiftThunkSources(_ printer: inout CodePrinter, ty: ImportedNominalType) throws {
    let stt = SwiftThunkTranslator(self)

    printer.print(
      """
      // Generated by swift-java

      import SwiftKitSwift

      """
    )

    for thunk in stt.renderThunks(forType: ty) {
      printer.print("\(thunk)")
      printer.print("")
    }
  }

  /// A module contains all static and global functions from the Swift module,
  /// potentially from across multiple swift interfaces.
  public func writeExportedJavaModule(outputDirectory: String) throws {
    var printer = CodePrinter()
    try writeExportedJavaModule(outputDirectory: outputDirectory, printer: &printer)
  }

  public func writeExportedJavaModule(outputDirectory: String, printer: inout CodePrinter) throws {
    printModule(&printer)

    if let file = try printer.writeContents(
      outputDirectory: outputDirectory,
      javaPackagePath: javaPackagePath,
      filename: "\(swiftModuleName).java"
    ) {
      self.log.info("Generated: \(file): \("done".green).")
    }
  }
}

// ==== ---------------------------------------------------------------------------------------------------------------
// MARK: Java/text printing

extension Swift2JavaTranslator {

  /// Render the Java file contents for an imported Swift module.
  ///
  /// This includes any Swift global functions in that module, and some general type information and helpers.
  public func printModule(_ printer: inout CodePrinter) {
    printHeader(&printer)
    printPackage(&printer)
    printImports(&printer)

    printModuleClass(&printer) { printer in
      // TODO: print all "static" methods
      for decl in importedGlobalFuncs {
        self.log.trace("Print imported decl: \(decl)")
        printFunctionDowncallMethods(&printer, decl)
      }
    }
  }

  package func printImportedClass(_ printer: inout CodePrinter, _ decl: ImportedNominalType) {
    printHeader(&printer)
    printPackage(&printer)
    printImports(&printer)

    printNominal(&printer, decl) { printer in
      // Prepare type metadata, we're going to need these when invoking e.g. initializers so cache them in a static.
      // We call into source swift-java source generated accessors which give us the type of the Swift object:
      // TODO: seems we no longer need the mangled name per se, so avoiding such constant and downcall
      //      printer.printParts(
      //        "public static final String TYPE_MANGLED_NAME = ",
      //        SwiftKitPrinting.renderCallGetSwiftTypeMangledName(module: self.swiftModuleName, nominal: decl),
      //        ";"
      //      )

      // We use a static field to abuse the initialization order such that by the time we get type metadata,
      // we already have loaded the library where it will be obtained from.
      printer.printParts(
        """
        @SuppressWarnings("unused")
        private static final boolean INITIALIZED_LIBS = initializeLibs();
        static boolean initializeLibs() {
            System.loadLibrary(SwiftKit.STDLIB_DYLIB_NAME);
            System.loadLibrary("SwiftKitSwift");
            System.loadLibrary(LIB_NAME);
            return true;
        }

        public static final SwiftAnyType TYPE_METADATA =
            new SwiftAnyType(\(SwiftKitPrinting.renderCallGetSwiftType(module: self.swiftModuleName, nominal: decl)));
        public final SwiftAnyType $swiftType() {
            return TYPE_METADATA;
        }
        """
      )
      printer.print("")

      // Layout of the class
      printClassMemoryLayout(&printer, decl)

      printer.print("")

      // Initializers
      for initDecl in decl.initializers {
        printClassConstructors(&printer, initDecl)
      }

      // Properties
      for varDecl in decl.variables {
        printVariableDowncallMethods(&printer, varDecl)
      }

      // Methods
      for funcDecl in decl.methods {
        printFunctionDowncallMethods(&printer, funcDecl)
      }

      // Helper methods and default implementations
      printHeapObjectToStringMethod(&printer, decl)
    }
  }

  public func printHeader(_ printer: inout CodePrinter) {
    printer.print(
      """
      // Generated by jextract-swift
      // Swift module: \(swiftModuleName)

      """
    )
  }

  public func printPackage(_ printer: inout CodePrinter) {
    printer.print(
      """
      package \(javaPackage);

      """
    )
  }

  public func printImports(_ printer: inout CodePrinter) {
    for i in Swift2JavaTranslator.defaultJavaImports {
      printer.print("import \(i);")
    }
    printer.print("")
  }

  package func printNominal(
    _ printer: inout CodePrinter, _ decl: ImportedNominalType, body: (inout CodePrinter) -> Void
  ) {
    let parentProtocol: String
    if decl.isReferenceType {
      parentProtocol = "SwiftHeapObject"
    } else {
      parentProtocol = "SwiftValue"
    }

    printer.printTypeDecl("public final class \(decl.javaClassName) extends SwiftInstance implements \(parentProtocol)") {
      printer in

      // Constants
      printClassConstants(printer: &printer)

      body(&printer)
    }
  }

  public func printModuleClass(_ printer: inout CodePrinter, body: (inout CodePrinter) -> Void) {
    printer.printTypeDecl("public final class \(swiftModuleName)") { printer in
      printPrivateConstructor(&printer, swiftModuleName)

      // Constants
      printClassConstants(printer: &printer)

      printer.print(
        """
        static MemorySegment findOrThrow(String symbol) {
            return SYMBOL_LOOKUP.find(symbol)
                    .orElseThrow(() -> new UnsatisfiedLinkError("unresolved symbol: %s".formatted(symbol)));
        }
        """
      )

      printer.print(
        """
        static MethodHandle upcallHandle(Class<?> fi, String name, FunctionDescriptor fdesc) {
            try {
                return MethodHandles.lookup().findVirtual(fi, name, fdesc.toMethodType());
            } catch (ReflectiveOperationException ex) {
                throw new AssertionError(ex);
            }
        }
        """
      )

      printer.print(
        """
        static MemoryLayout align(MemoryLayout layout, long align) {
            return switch (layout) {
                case PaddingLayout p -> p;
                case ValueLayout v -> v.withByteAlignment(align);
                case GroupLayout g -> {
                    MemoryLayout[] alignedMembers = g.memberLayouts().stream()
                            .map(m -> align(m, align)).toArray(MemoryLayout[]::new);
                    yield g instanceof StructLayout ?
                            MemoryLayout.structLayout(alignedMembers) : MemoryLayout.unionLayout(alignedMembers);
                }
                case SequenceLayout s -> MemoryLayout.sequenceLayout(s.elementCount(), align(s.elementLayout(), align));
            };
        }
        """
      )

      // SymbolLookup.libraryLookup is platform dependent and does not take into account java.library.path
      // https://bugs.openjdk.org/browse/JDK-8311090
      printer.print(
        """
        static final SymbolLookup SYMBOL_LOOKUP = getSymbolLookup();
        private static SymbolLookup getSymbolLookup() {
            // Ensure Swift and our Lib are loaded during static initialization of the class.
            SwiftKit.loadLibrary("swiftCore");
            SwiftKit.loadLibrary("SwiftKitSwift");
            SwiftKit.loadLibrary(LIB_NAME);

            if (PlatformUtils.isMacOS()) {
                return SymbolLookup.libraryLookup(System.mapLibraryName(LIB_NAME), LIBRARY_ARENA)
                        .or(SymbolLookup.loaderLookup())
                        .or(Linker.nativeLinker().defaultLookup());
            } else {
                return SymbolLookup.loaderLookup()
                        .or(Linker.nativeLinker().defaultLookup());
            }
        }
        """
      )

      body(&printer)
    }
  }

  private func printClassConstants(printer: inout CodePrinter) {
    printer.print(
      """
      static final String LIB_NAME = "\(swiftModuleName)";
      static final Arena LIBRARY_ARENA = Arena.ofAuto();
      """
    )
  }

  private func printPrivateConstructor(_ printer: inout CodePrinter, _ typeName: String) {
    printer.print(
      """
      private \(typeName)() {
        // Should not be called directly
      }

      // Static enum to force initialization
      private static enum Initializer {
        FORCE; // Refer to this to force outer Class initialization (and static{} blocks to trigger)
      }
      """
    )
  }

  private func printClassMemoryLayout(_ printer: inout CodePrinter, _ decl: ImportedNominalType) {
    printer.print(
      """
      private static final GroupLayout $LAYOUT = (GroupLayout) SwiftValueWitnessTable.layoutOfSwiftType(TYPE_METADATA.$memorySegment());

      public final GroupLayout $layout() {
          return $LAYOUT;
      }
      """
    )
  }

  public func printClassConstructors(_ printer: inout CodePrinter, _ decl: ImportedFunc) {
    guard let parentName = decl.parent else {
      fatalError("init must be inside a parent type! Was: \(decl)")
    }
    printer.printSeparator(decl.identifier)

    let descClassIdentifier = renderDescClassName(decl)
    printer.printTypeDecl("private static class \(descClassIdentifier)") { printer in
      printFunctionDescriptorValue(&printer, decl)
      printAccessorFunctionAddr(&printer, decl)
      printMethodDowncallHandleForAddrDesc(&printer)
    }

    printNominalInitializerConstructors(&printer, decl, parentName: parentName)
  }

  public func printNominalInitializerConstructors(
    _ printer: inout CodePrinter,
    _ decl: ImportedFunc,
    parentName: TranslatedType
  ) {
    let descClassIdentifier = renderDescClassName(decl)

    printer.print(
      """
      /**
       * Create an instance of {@code \(parentName.unqualifiedJavaTypeName)}.
       *
      \(decl.renderCommentSnippet ?? " *")
       */
      public \(parentName.unqualifiedJavaTypeName)(\(renderJavaParamDecls(decl, paramPassingStyle: .wrapper))) {
        this(SwiftArena.ofAuto(), \(renderForwardJavaParams(decl, paramPassingStyle: .wrapper)));
      }
      """
    )

    printer.print(
      """
      /**
       * Create an instance of {@code \(parentName.unqualifiedJavaTypeName)}.
       * This instance is managed by the passed in {@link SwiftArena} and may not outlive the arena's lifetime.
       *
      \(decl.renderCommentSnippet ?? " *")
       */
      public \(parentName.unqualifiedJavaTypeName)(SwiftArena arena, \(renderJavaParamDecls(decl, paramPassingStyle: .wrapper))) {
        super(() -> {
          var mh$ = \(descClassIdentifier).HANDLE;
          try {
            MemorySegment _result = arena.allocate($LAYOUT);
      
            if (SwiftKit.TRACE_DOWNCALLS) {
              SwiftKit.traceDowncall(\(renderForwardJavaParams(decl, paramPassingStyle: nil)));
            }
            mh$.invokeExact(
              \(renderForwardJavaParams(decl, paramPassingStyle: nil)),
              /* indirect return buffer */_result
            );
            return _result;
          } catch (Throwable ex$) {
              throw new AssertionError("should not reach here", ex$);
          }
        }, arena);
      }
      """
    )
  }

  public func printFunctionDowncallMethods(_ printer: inout CodePrinter, _ decl: ImportedFunc) {
    printer.printSeparator(decl.identifier)

    printer.printTypeDecl("private static class \(decl.baseIdentifier)") { printer in
      printFunctionDescriptorValue(&printer, decl)
      printAccessorFunctionAddr(&printer, decl)
      printMethodDowncallHandleForAddrDesc(&printer)
    }

    printFunctionDescriptorMethod(&printer, decl: decl)
    printFunctionMethodHandleMethod(&printer, decl: decl)
    printFunctionAddressMethod(&printer, decl: decl)

    // Render the basic "make the downcall" function
    if decl.hasParent {
      printFuncDowncallMethod(&printer, decl: decl, paramPassingStyle: .memorySegment)
      printFuncDowncallMethod(&printer, decl: decl, paramPassingStyle: .wrapper)
    } else {
      printFuncDowncallMethod(&printer, decl: decl, paramPassingStyle: nil)
    }
  }

  private func printFunctionAddressMethod(
    _ printer: inout CodePrinter,
    decl: ImportedFunc,
    accessorKind: VariableAccessorKind? = nil
  ) {

    let addrName = accessorKind.renderAddrFieldName
    let methodNameSegment = accessorKind.renderMethodNameSegment
    let snippet = decl.renderCommentSnippet ?? "* "

    printer.print(
      """
      /**
       * Address for:
      \(snippet)
       */
      public static MemorySegment \(decl.baseIdentifier)\(methodNameSegment)$address() {
          return \(decl.baseIdentifier).\(addrName);
      }
      """
    )
  }

  private func printFunctionMethodHandleMethod(
    _ printer: inout CodePrinter,
    decl: ImportedFunc,
    accessorKind: VariableAccessorKind? = nil
  ) {
    let handleName = accessorKind.renderHandleFieldName
    let methodNameSegment = accessorKind.renderMethodNameSegment
    let snippet = decl.renderCommentSnippet ?? "* "

    printer.print(
      """
      /**
       * Downcall method handle for:
      \(snippet)
       */
      public static MethodHandle \(decl.baseIdentifier)\(methodNameSegment)$handle() {
          return \(decl.baseIdentifier).\(handleName);
      }
      """
    )
  }

  private func printFunctionDescriptorMethod(
    _ printer: inout CodePrinter,
    decl: ImportedFunc,
    accessorKind: VariableAccessorKind? = nil
  ) {
    let descName = accessorKind.renderDescFieldName
    let methodNameSegment = accessorKind.renderMethodNameSegment
    let snippet = decl.renderCommentSnippet ?? "* "

    printer.print(
      """
      /**
       * Function descriptor for:
      \(snippet)
       */
      public static FunctionDescriptor \(decl.baseIdentifier)\(methodNameSegment)$descriptor() {
          return \(decl.baseIdentifier).\(descName);
      }
      """
    )
  }

  public func printVariableDowncallMethods(_ printer: inout CodePrinter, _ decl: ImportedVariable) {
    printer.printSeparator(decl.identifier)

    printer.printTypeDecl("private static class \(decl.baseIdentifier)") { printer in
      for accessorKind in decl.supportedAccessorKinds {
        guard let accessor = decl.accessorFunc(kind: accessorKind) else {
          log.warning("Skip print for \(accessorKind) of \(decl.identifier)!")
          continue
        }

        printFunctionDescriptorValue(&printer, accessor, accessorKind: accessorKind)
        printAccessorFunctionAddr(&printer, accessor, accessorKind: accessorKind)
        printMethodDowncallHandleForAddrDesc(&printer, accessorKind: accessorKind)
      }
    }

    // First print all the supporting infra
    for accessorKind in decl.supportedAccessorKinds {
      guard let accessor = decl.accessorFunc(kind: accessorKind) else {
        log.warning("Skip print for \(accessorKind) of \(decl.identifier)!")
        continue
      }
      printFunctionDescriptorMethod(&printer, decl: accessor, accessorKind: accessorKind)
      printFunctionMethodHandleMethod(&printer, decl: accessor, accessorKind: accessorKind)
      printFunctionAddressMethod(&printer, decl: accessor, accessorKind: accessorKind)
    }

    // Then print the actual downcall methods
    for accessorKind in decl.supportedAccessorKinds {
      guard let accessor = decl.accessorFunc(kind: accessorKind) else {
        log.warning("Skip print for \(accessorKind) of \(decl.identifier)!")
        continue
      }

      // Render the basic "make the downcall" function
      if decl.hasParent {
        printFuncDowncallMethod(
          &printer, decl: accessor, paramPassingStyle: .memorySegment, accessorKind: accessorKind)
        printFuncDowncallMethod(
          &printer, decl: accessor, paramPassingStyle: .wrapper, accessorKind: accessorKind)
      } else {
        printFuncDowncallMethod(
          &printer, decl: accessor, paramPassingStyle: nil, accessorKind: accessorKind)
      }
    }
  }

  func printAccessorFunctionAddr(
    _ printer: inout CodePrinter, _ decl: ImportedFunc,
    accessorKind: VariableAccessorKind? = nil
  ) {
    let thunkName = thunkNameRegistry.functionThunkName(module: self.swiftModuleName, decl: decl)
    printer.print(
      """
      public static final MemorySegment \(accessorKind.renderAddrFieldName) =
        \(self.swiftModuleName).findOrThrow("\(thunkName)");
      """
    )
  }

  func printMethodDowncallHandleForAddrDesc(
    _ printer: inout CodePrinter, accessorKind: VariableAccessorKind? = nil
  ) {
    printer.print(
      """
      public static final MethodHandle \(accessorKind.renderHandleFieldName) = Linker.nativeLinker().downcallHandle(\(accessorKind.renderAddrFieldName), \(accessorKind.renderDescFieldName));
      """
    )
  }

  public func printFuncDowncallMethod(
    _ printer: inout CodePrinter,
    decl: ImportedFunc,
    paramPassingStyle: SelfParameterVariant?,
    accessorKind: VariableAccessorKind? = nil
  ) {
    let returnTy = decl.returnType.javaType

    let maybeReturnCast: String
    if decl.returnType.javaType == .void {
      maybeReturnCast = ""  // nothing to return or cast to
    } else {
      maybeReturnCast = "return (\(returnTy))"
    }

    // TODO: we could copy the Swift method's documentation over here, that'd be great UX
    let javaDocComment: String =
      """
      /**
       * Downcall to Swift:
      \(decl.renderCommentSnippet ?? "* ")
       */
      """

    // An identifier may be "getX", "setX" or just the plain method name
    let identifier = accessorKind.renderMethodName(decl)

    if paramPassingStyle == SelfParameterVariant.wrapper {
      let guardFromDestroyedObjectCalls: String =
      if decl.hasParent {
        """
        $ensureAlive();
        """
      } else { "" }

      // delegate to the MemorySegment "self" accepting overload
      printer.print(
        """
        \(javaDocComment)
        public \(returnTy) \(identifier)(\(renderJavaParamDecls(decl, paramPassingStyle: .wrapper))) {
          \(guardFromDestroyedObjectCalls)
          \(maybeReturnCast) \(identifier)(\(renderForwardJavaParams(decl, paramPassingStyle: .wrapper)));
        }
        """
      )
      return
    }

    let needsArena = downcallNeedsConfinedArena(decl)
    let handleName = accessorKind.renderHandleFieldName

    printer.printParts(
      """
      \(javaDocComment)
      public static \(returnTy) \(identifier)(\(renderJavaParamDecls(decl, paramPassingStyle: paramPassingStyle))) {
        var mh$ = \(decl.baseIdentifier).\(handleName);
        \(renderTry(withArena: needsArena))
      """,
      renderUpcallHandles(decl),
      renderParameterDowncallConversions(decl),
      """
          if (SwiftKit.TRACE_DOWNCALLS) {
             SwiftKit.traceDowncall(\(renderForwardJavaParams(decl, paramPassingStyle: .memorySegment)));
          }
          \(maybeReturnCast) mh$.invokeExact(\(renderForwardJavaParams(decl, paramPassingStyle: paramPassingStyle)));
        } catch (Throwable ex$) {
          throw new AssertionError("should not reach here", ex$);
        }
      }
      """
    )
  }

  public func printPropertyAccessorDowncallMethod(
    _ printer: inout CodePrinter,
    decl: ImportedFunc,
    paramPassingStyle: SelfParameterVariant?
  ) {
    let returnTy = decl.returnType.javaType

    let maybeReturnCast: String
    if decl.returnType.javaType == .void {
      maybeReturnCast = ""  // nothing to return or cast to
    } else {
      maybeReturnCast = "return (\(returnTy))"
    }

    if paramPassingStyle == SelfParameterVariant.wrapper {
      // delegate to the MemorySegment "self" accepting overload
      printer.print(
        """
        /**
         * {@snippet lang=swift :
         * \(/*TODO: make a printSnippet func*/decl.syntax ?? "")
         * }
         */
        public \(returnTy) \(decl.baseIdentifier)(\(renderJavaParamDecls(decl, paramPassingStyle: .wrapper))) {
          \(maybeReturnCast) \(decl.baseIdentifier)(\(renderForwardJavaParams(decl, paramPassingStyle: .wrapper)));
        }
        """
      )
      return
    }

    printer.print(
      """
      /**
       * {@snippet lang=swift :
       * \(/*TODO: make a printSnippet func*/decl.syntax ?? "")
       * }
       */
      public static \(returnTy) \(decl.baseIdentifier)(\(renderJavaParamDecls(decl, paramPassingStyle: paramPassingStyle))) {
        var mh$ = \(decl.baseIdentifier).HANDLE;
        try {
          if (SwiftKit.TRACE_DOWNCALLS) {
             SwiftKit.traceDowncall(\(renderForwardJavaParams(decl, paramPassingStyle: .memorySegment)));
          }
          \(maybeReturnCast) mh$.invokeExact(\(renderForwardJavaParams(decl, paramPassingStyle: paramPassingStyle)));
        } catch (Throwable ex$) {
          throw new AssertionError("should not reach here", ex$);
        }
      }
      """
    )
  }

  /// Given a function like `init(cap:name:)`, renders a name like `init_cap_name`
  public func renderDescClassName(_ decl: ImportedFunc) -> String {
    var ps: [String] = [decl.baseIdentifier]
    var pCounter = 0

    func nextUniqueParamName() -> String {
      pCounter += 1
      return "p\(pCounter)"
    }

    for p in decl.effectiveParameters(paramPassingStyle: nil) {
      let param = "\(p.effectiveName ?? nextUniqueParamName())"
      ps.append(param)
    }

    let res = ps.joined(separator: "_")
    return res
  }

  /// Do we need to construct an inline confined arena for the duration of the downcall?
  public func downcallNeedsConfinedArena(_ decl: ImportedFunc) -> Bool {
    for p in decl.parameters {
      // We need to detect if any of the parameters is a closure we need to prepare
      // an upcall handle for.
      if p.type.javaType.isSwiftClosure {
        return true
      }

      if p.type.javaType.isString {
        return true
      }
    }

    return false
  }

  public func renderTry(withArena: Bool) -> String {
    if withArena {
      "try (var arena = Arena.ofConfined()) {"
    } else {
      "try {"
    }
  }

  public func renderJavaParamDecls(_ decl: ImportedFunc, paramPassingStyle: SelfParameterVariant?) -> String {
    var ps: [String] = []
    var pCounter = 0

    func nextUniqueParamName() -> String {
      pCounter += 1
      return "p\(pCounter)"
    }

    for p in decl.effectiveParameters(paramPassingStyle: paramPassingStyle) {
      let param = "\(p.type.javaType.description) \(p.effectiveName ?? nextUniqueParamName())"
      ps.append(param)
    }

    let res = ps.joined(separator: ", ")
    return res
  }

  // TODO: these are stateless, find new place for them?
  public func renderSwiftParamDecls(
    _ decl: ImportedFunc,
    paramPassingStyle: SelfParameterVariant?,
    style: ParameterVariant? = nil
  ) -> String {
    var ps: [String] = []
    var pCounter = 0

    func nextUniqueParamName() -> String {
      pCounter += 1
      return "p\(pCounter)"
    }

    for p in decl.effectiveParameters(paramPassingStyle: paramPassingStyle) {
      let firstName = p.firstName ?? "_"
      let secondName = p.secondName ?? p.firstName ?? nextUniqueParamName()

      let paramTy: String =
        if style == .cDeclThunk, p.type.javaType.isString {
          "UnsafeMutablePointer<CChar>"  // TODO: is this ok?
        } else if paramPassingStyle == .swiftThunkSelf {
          "\(p.type.cCompatibleSwiftType)"
        } else {
          p.type.swiftTypeName.description
        }

      let param =
        if firstName == secondName {
          // We have to do this to avoid a 'extraneous duplicate parameter name; 'number' already has an argument label' warning
          "\(firstName): \(paramTy)"
        } else {
          "\(firstName) \(secondName): \(paramTy)"
        }
      ps.append(param)
    }

    if paramPassingStyle == .swiftThunkSelf {
      ps.append("_self: UnsafeMutableRawPointer")
    }

    let res = ps.joined(separator: ", ")
    return res
  }

  public func renderUpcallHandles(_ decl: ImportedFunc) -> String {
    var printer = CodePrinter()
    for p in decl.parameters where p.type.javaType.isSwiftClosure {
      if p.type.javaType == .javaLangRunnable {
        let paramName = p.secondName ?? p.firstName ?? "_"
        let handleDesc = p.type.javaType.prepareClosureDowncallHandle(
          decl: decl, parameter: paramName)
        printer.print(handleDesc)
      }
    }

    return printer.contents
  }

  public func renderParameterDowncallConversions(_ decl: ImportedFunc) -> String {
    var printer = CodePrinter()
    for p in decl.parameters {
      if p.type.javaType.isString {
        printer.print(
          """
          var \(p.effectiveValueName)$ = arena.allocateFrom(\(p.effectiveValueName));
          """
        )
      }
    }

    return printer.contents
  }

  public func renderForwardJavaParams(
    _ decl: ImportedFunc, paramPassingStyle: SelfParameterVariant?
  ) -> String {
    var ps: [String] = []
    var pCounter = 0

    func nextUniqueParamName() -> String {
      pCounter += 1
      return "p\(pCounter)"
    }

    for p in decl.effectiveParameters(paramPassingStyle: paramPassingStyle) {
      // FIXME: fix the handling here we're already a memory segment
      let param: String
      if p.effectiveName == "self$" {
        precondition(paramPassingStyle == .memorySegment)
        param = "self$"
      } else if p.type.javaType.isString {
        // TODO: make this less one-off and maybe call it "was adapted"?
        if paramPassingStyle == .wrapper {
          // pass it raw, we're not performing adaptation here it seems as we're passing wrappers around
          param = "\(p.effectiveValueName)"
        } else {
          param = "\(p.effectiveValueName)$"
        }
      } else {
        param = "\(p.renderParameterForwarding() ?? nextUniqueParamName())"
      }
      ps.append(param)
    }

    // Add the forwarding "self"
    if paramPassingStyle == .wrapper && !decl.isInit {
      ps.append("$memorySegment()")
    }

    return ps.joined(separator: ", ")
  }

  // TODO: these are stateless, find new place for them?
  public func renderForwardSwiftParams(
    _ decl: ImportedFunc, paramPassingStyle: SelfParameterVariant?
  ) -> String {
    var ps: [String] = []

    for p in decl.effectiveParameters(paramPassingStyle: paramPassingStyle) {
      if let firstName = p.firstName {
        ps.append("\(firstName): \(p.effectiveValueName)")
      } else {
        ps.append("\(p.effectiveValueName)")
      }
    }

    return ps.joined(separator: ", ")
  }

  public func printFunctionDescriptorValue(
    _ printer: inout CodePrinter,
    _ decl: ImportedFunc,
    accessorKind: VariableAccessorKind? = nil
  ) {
    let fieldName = accessorKind.renderDescFieldName
    printer.start("public static final FunctionDescriptor \(fieldName) = ")

    let isIndirectReturn = decl.isIndirectReturn

    let parameterLayoutDescriptors: [ForeignValueLayout] = javaMemoryLayoutDescriptors(
      forParametersOf: decl,
      paramPassingStyle: .pointer
    )

    if decl.returnType.javaType == .void || isIndirectReturn {
      printer.print("FunctionDescriptor.ofVoid(")
      printer.indent()
    } else {
      printer.print("FunctionDescriptor.of(")
      printer.indent()

      // Write return type
      let returnTyIsLastTy = decl.parameters.isEmpty && !decl.hasParent
      if decl.isInit {
        // when initializing, we return a pointer to the newly created object
        printer.print(
          "/* -> */\(ForeignValueLayout.SwiftPointer)", .parameterNewlineSeparator(returnTyIsLastTy)
        )
      } else {
        var returnDesc = decl.returnType.foreignValueLayout
        returnDesc.inlineComment = " -> "
        printer.print(returnDesc, .parameterNewlineSeparator(returnTyIsLastTy))
      }
    }

    // Write all parameters (including synthesized ones, like self)
    for (desc, isLast) in parameterLayoutDescriptors.withIsLast {
      printer.print(desc, .parameterNewlineSeparator(isLast))
    }

    printer.outdent()
    printer.print(");")
  }

  package func printHeapObjectToStringMethod(
    _ printer: inout CodePrinter, _ decl: ImportedNominalType
  ) {
    printer.print(
      """
      @Override
      public String toString() {
          return getClass().getSimpleName() + "(" +
                  SwiftKit.nameOfSwiftType($swiftType().$memorySegment(), true) +
                  ")@" + $memorySegment();
      }
      """)
  }

}