293 lines
8.3 KiB
D
293 lines
8.3 KiB
D
/**
|
||
* 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;
|