Skip to content

Built-in annotations

The language comes with some pre-defined annotations listed here. The compiler uses them for code generation and other purposes such as deprecation warnings.

The Crystal standard library defines more annotations.

Tells the compiler how to link a C library. This is explained in the lib section.

Info

See the API docs for Link for more details.

Extern

Marking a Crystal struct with this annotation makes it possible to use it in lib declarations:

@[Extern]
struct MyStruct
end

lib MyLib
  fun my_func(s : MyStruct) # OK (gives an error without the Extern annotation)
end

You can also make a struct behave like a C union (this can be pretty unsafe):

# A struct to easily convert between Int32 codepoints and Chars
@[Extern(union: true)]
struct Int32OrChar
  property int = 0
  property char = '\0'
end

s = Int32OrChar.new
s.char = 'A'
s.int # => 65

s.int = 66
s.char # => 'B'

ThreadLocal

The @[ThreadLocal] annotation can be applied to class variables and C external variables. It makes them be thread local.

class DontUseThis
  # One for each thread
  @[ThreadLocal]
  @@values = [] of Int32
end

ThreadLocal is used in the standard library to implement the runtime and shouldn't be needed or used outside it.

Packed

Marks a C struct as packed, which prevents the automatic insertion of padding bytes between fields. This is typically only needed if the C library explicitly uses packed structs.

AlwaysInline

Gives a hint to the compiler to always inline a method:

@[AlwaysInline]
def foo
  1
end

NoInline

Tells the compiler to never inline a method call. This has no effect if the method yields, since functions which yield are always inlined.

@[NoInline]
def foo
  1
end

ReturnsTwice

Marks a method or lib fun as returning twice. The C setjmp is an example of such a function.

Raises

Marks a method or lib fun as potentially raising an exception. This is explained in the callbacks section.

CallConvention

Indicates the call convention of a lib fun. For example:

lib LibFoo
  @[CallConvention("X86_StdCall")]
  fun foo : Int32
end

The list of valid call conventions is:

  • C (the default)
  • Fast
  • Cold
  • WebKit_JS
  • AnyReg
  • X86_StdCall
  • X86_FastCall

Info

See LLVM documentation for more details.

Flags

Marks an enum as a "flags enum", which changes the behaviour of some of its methods, like to_s.

Info

See the API docs for Flags for more details.

Deprecated

Marks a feature (e.g. a method, type or parameter) as deprecated.

Deprecations are shown in the API docs and the compiler prints a warning when using a deprecated feature.

Info

See the API docs for Deprecated for more details.