/**
* This module contains UDA's (User Defined Attributes) either used in
* the runtime or special UDA's recognized by compiler.
*
* Copyright: Copyright Jacob Carlborg 2015.
* License: $(LINK2 http://www.boost.org/LICENSE_1_0.txt, Boost License 1.0)
* Authors: Jacob Carlborg
* Source: $(DRUNTIMESRC core/_attribute.d)
*/
/* Copyright Jacob Carlborg 2015.
* Distributed under the Boost Software License, Version 1.0.
* (See accompanying file LICENSE or copy at
* http://www.boost.org/LICENSE_1_0.txt)
*/
module core.attribute;
version (GNU)
public import gcc.attributes;
version (LDC)
public import ldc.attributes;
version (D_ObjectiveC)
{
version = UdaOptional;
version = UdaSelector;
}
version (Posix)
version = UdaGNUAbiTag;
version (CoreDdoc)
{
version = UdaGNUAbiTag;
version = UdaOptional;
version = UdaSelector;
}
/**
* Use this attribute to specify that a global symbol should be emitted with
* weak linkage. This is primarily useful in defining library functions that
* can be overridden by user code, though it can also be used with shared and
* static variables too.
*
* The overriding symbol must have the same type as the weak symbol. In
* addition, if it designates a variable it must also have the same size and
* alignment as the weak symbol.
*
* Quote from the LLVM manual: "Note that weak linkage does not actually allow
* the optimizer to inline the body of this function into callers because it
* doesn’t know if this definition of the function is the definitive definition
* within the program or whether it will be overridden by a stronger
* definition."
*
* This attribute is only meaningful to the GNU and LLVM D compilers. The
* Digital Mars D compiler emits all symbols with weak linkage by default.
*/
version (DigitalMars)
{
enum weak;
}
else
{
// GDC and LDC declare this attribute in their own modules.
}
/**
* Use this attribute to attach an Objective-C selector to a method.
*
* This is a special compiler recognized attribute, it has several
* requirements, which all will be enforced by the compiler:
*
* $(UL
* $(LI
* The attribute can only be attached to methods or constructors which
* have Objective-C linkage. That is, a method or a constructor in a
* class or interface declared as $(D_CODE extern(Objective-C)).
* ),
*
* $(LI It cannot be attached to a method or constructor that is a template),
*
* $(LI
* The number of colons in the string need to match the number of
* arguments the method accept.
* ),
*
* $(LI It can only be used once in a method declaration)
* )
*
* Examples:
* ---
* extern (Objective-C)
* class NSObject
* {
* this() @selector("init");
* static NSObject alloc() @selector("alloc");
* NSObject initWithUTF8String(in char* str) @selector("initWithUTF8String:");
* ObjcObject copyScriptingValue(ObjcObject value, NSString key, NSDictionary properties)
* @selector("copyScriptingValue:forKey:withProperties:");
* }
* ---
*/
version (UdaSelector) struct selector
{
string selector;
}
/**
* Use this attribute to make an Objective-C interface method optional.
*
* An optional method is a method that does **not** have to be implemented in
* the class that implements the interface. To safely call an optional method,
* a runtime check should be performed to make sure the receiver implements the
* method.
*
* This is a special compiler recognized attribute, it has several
* requirements, which all will be enforced by the compiler:
*
* * The attribute can only be attached to methods which have Objective-C
* linkage. That is, a method inside an interface declared as `extern (Objective-C)`
*
* * It can only be used for methods that are declared inside an interface
* * It can only be used once in a method declaration
* * It cannot be attached to a method that is a template
*
* Examples:
* ---
* import core.attribute : optional, selector;
*
* extern (Objective-C):
*
* struct objc_selector;
* alias SEL = objc_selector*;
*
* SEL sel_registerName(in char* str);
*
* extern class NSObject
* {
* bool respondsToSelector(SEL sel) @selector("respondsToSelector:");
* }
*
* interface Foo
* {
* @optional void foo() @selector("foo");
* @optional void bar() @selector("bar");
* }
*
* class Bar : NSObject
* {
* static Bar alloc() @selector("alloc");
* Bar init() @selector("init");
*
* void bar() @selector("bar")
* {
* }
* }
*
* extern (D) void main()
* {
* auto bar = Bar.alloc.init;
*
* if (bar.respondsToSelector(sel_registerName("bar")))
* bar.bar();
* }
* ---
*/
version (UdaOptional)
enum optional;
/**
* Use this attribute to declare an ABI tag on a C++ symbol.
*
* ABI tag is an attribute introduced by the GNU C++ compiler.
* It modifies the mangled name of the symbol to incorporate the tag name,
* in order to distinguish from an earlier version with a different ABI.
*
* This is a special compiler recognized attribute, it has a few
* requirements, which all will be enforced by the compiler:
*
* $(UL
* $(LI
* There can only be one such attribute per symbol.
* ),
* $(LI
* The attribute can only be attached to an `extern(C++)` symbol
* (`struct`, `class`, `enum`, function, and their templated counterparts).
* ),
* $(LI
* The attribute cannot be applied to C++ namespaces.
* This is to prevent confusion with the C++ semantic, which allows it to
* be applied to namespaces.
* ),
* $(LI
* The string arguments must only contain valid characters
* for C++ name mangling which currently include alphanumerics
* and the underscore character.
* ),
* )
*
* This UDA is not transitive, and inner scope do not inherit outer scopes'
* ABI tag. See examples below for how to translate a C++ declaration to D.
* Also note that entries in this UDA will be automatically sorted
* alphabetically, hence `gnuAbiTag("c", "b", "a")` will appear as
* `@gnuAbiTag("a", "b", "c")`.
*
* See_Also:
* $(LINK2 https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.abi-tag, Itanium ABI spec)
* $(LINK2 https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html, GCC attributes documentation).
*
* Examples:
* ---
* // ---- foo.cpp
* struct [[gnu::abi_tag ("tag1", "tag2")]] Tagged1_2
* {
* struct [[gnu::abi_tag ("tag3")]] Tagged3
* {
* [[gnu::abi_tag ("tag4")]]
* int Tagged4 () { return 42; }
* }
* }
* Tagged1_2 inst1;
* // ---- foo.d
* @gnuAbiTag("tag1", "tag2") struct Tagged1_2
* {
* // Notice the repetition
* @gnuAbiTag("tag1", "tag2", "tag3") struct Tagged3
* {
* @gnuAbiTag("tag1", "tag2", "tag3", "tag4") int Tagged4 ();
* }
* }
* extern __gshared Tagged1_2 inst1;
* ---
*/
version (UdaGNUAbiTag) struct gnuAbiTag
{
string[] tags;
this(string[] tags...)
{
this.tags = tags;
}
}
/**
* Use this attribute to ensure that values of a `struct` or `union` type are
* not discarded.
*
* The value of an expression is considered to be discarded if
*
* $(UL
* $(LI
* the expression is the top-level expression in a statement or the
* left-hand expression in a comma expression, and
* ),
* $(LI
* the expression is not an assignment (`=`, `+=`, etc.), increment
* (`++`), or decrement (`--`) expression.
* ),
* )
*
* If the declaration of a `struct` or `union` type has the `@mustuse`
* attribute, the compiler will emit an error any time a value of that type
* would be discarded.
*
* Currently, `@mustuse` is only recognized by the compiler when attached to
* `struct` and `union` declarations. To allow for future expansion, attaching
* `@mustuse` to a `class`, `interface`, `enum`, or function declaration is
* currently forbidden, and will result in a compile-time error. All other uses
* of `@mustuse` are ignored.
*
* Examples:
* ---
* @mustuse struct ErrorCode { int value; }
*
* extern(C) ErrorCode doSomething();
*
* void main()
* {
* // error: would discard a value of type ErrorCode
* //doSomething();
*
* ErrorCode result;
* // ok: value is assigned to a variable
* result = doSomething();
*
* // ok: can ignore the value explicitly with a cast
* cast(void) doSomething();
* }
* ---
*/
enum mustuse;