External Procedures¶

EXTERN_PROCEDURE declares a callable symbol supplied by another binary or runtime environment. The declaration gives the external identity, Quxlang call shape, and calling convention.

Declaration syntax¶

::malloc INCLUDE_IF(ENVIRONMENT_IS_GLIBC)
  EXTERN_PROCEDURE["glibc":"malloc" VERSION "GLIBC_2.2.5"]
  CALLABLE CALLCONV CCALL(@bytes SZ; RETURN ADDRESS);

The declaration consists of:

a library or external scope string;
an external symbol-name string;
optional configuration such as VERSION or OPTIONAL;
a CALLABLE signature;
an optional explicit CALLCONV; and
a terminating semicolon.

CALLCONV CCALL selects the C ABI. When CALLCONV is omitted, the declaration uses CCALL.

Parameters and return type¶

Parameters may be named or positional. The optional return type follows a semicolon inside CALLABLE:

::native_operation
  EXTERN_PROCEDURE["native":"operation"]
  CALLABLE(@input I32, U64; RETURN BOOL);

Named parameters use the ordinary Quxlang call-argument mapping. An unnamed parameter is supplied positionally. A declaration without ; RETURN Type has no result.

Versions and optional symbols¶

::optional_extension INCLUDE_IF(ENVIRONMENT_IS_GLIBC)
  EXTERN_PROCEDURE["extension":"try_feature" OPTIONAL]
  CALLABLE(@value I32; RETURN I32);

VERSION "name" records the required external symbol version. OPTIONAL permits the external symbol to be absent during linking or loading. It does not make an unconditional call safe: the program remains responsible for calling the symbol only where the target and runtime provide it.

JVM call conventions¶

Managed backends use conventions that identify the represented bytecode operation:

Convention	External operation	Parameter shape
`JVM_STATIC`	Invoke a static method	Ordinary parameters; optional return
`JVM_VIRTUAL`	Invoke a virtual method	`@THIS` plus method parameters
`JVM_INTERFACE`	Invoke an interface method	`@THIS` plus method parameters
`JVM_CONSTRUCTOR`	Construct an instance	Constructor parameters; GC pointer return
`JVM_GETFIELD`	Read an instance field	`@THIS`; field-value return
`JVM_PUTFIELD`	Write an instance field	`@THIS` and `@VALUE`
`JVM_GETSTATIC`	Read a static field	No receiver; field-value return
`JVM_PUTSTATIC`	Write a static field	`@VALUE`

For example:

::system_out INCLUDE_IF(ARCH_IS_JVM)
  EXTERN_PROCEDURE["java/lang/System":"out"]
  CALLABLE CALLCONV JVM_GETSTATIC(; RETURN ~>java_print_stream);

::java_point_constructor INCLUDE_IF(ARCH_IS_JVM)
  EXTERN_PROCEDURE["java/awt/Point":"<init>"]
  CALLABLE CALLCONV JVM_CONSTRUCTOR(
    @x I32, @y I32; RETURN ~>java_point
  );

The declared receiver and value parameters must match the selected convention. The returned GC pointer target type is declared with External Types.

Availability and ABI requirements¶

The calling convention, parameter types, result type, external identity, and symbol version form an ABI contract. The Quxlang type system cannot repair a mismatch. INCLUDE_IF and target predicates restrict declarations to compatible targets.

See Call Arguments, Target Availability, and The qxcbuild.yml File.

Mach-O library identities¶

For macOS native imports, the library string is the literal Mach-O install name. Quxlang preserves the name in the linked image. The declaration must contain the platform library's absolute install path where the platform requires that path:

::native_malloc INCLUDE_IF(OS_MACOS)
  EXTERN_PROCEDURE["/usr/lib/libSystem.B.dylib":"malloc"]
  CALLABLE CALLCONV CCALL(@bytes SZ; RETURN ADDRESS);