Attributes - D Programming Language 2.0 - Digital Mars
Description: D Programming Language
Keywords: D programming language

D Programming Language 2.0

- Forum
- Wiki
- Search
- Downloads
- Home

Last update Sun Jan 22 16:54:30 2012

# Attributes

    AttributeSpecifier:
        Attribute :
        Attribute DeclarationBlock

    Attribute:
        LinkageAttribute
        AlignAttribute
        Pragma
        deprecated
        ProtectionAttribute
        static
        extern
        final
        synchronized
        override
        abstract
        const
        auto
        scope
        __gshared
        shared
        immutable
        inout
        @disable

    DeclarationBlock:
        DeclDef
        { DeclDefsopt }

Attributes are a way to modify one or more declarations. The general forms are:

    attribute declaration; // affects the declaration

    attribute:     // affects all declarations until the end of
                   // the current scope
      declaration;
      declaration;
      ...

    attribute {    // affects all declarations in the block
      declaration;
      declaration;
      ...
    }

## Linkage Attribute

    LinkageAttribute:
        extern ( LinkageType )

    LinkageType:
        C
        C++
        D
        Windows
        Pascal
        System

D provides an easy way to call C functions and operating system API functions, as compatibility with both is essential. The LinkageType is case sensitive, and is meant to be extensible by the implementation (they are not keywords). C and D must be supplied, the others are what makes sense for the implementation. C++ is reserved for future use. System is the same as Windows on Windows platforms, and C on other platforms. Implementation Note: for Win32 platforms, Windows and Pascal should exist.

C function calling conventions are specified by:

    extern (C):
      int foo(); // call foo() with C conventions

D conventions are:

    extern (D):

or:

    extern:

Windows API conventions are:

    extern (Windows):
      void *VirtualAlloc(
        void *lpAddress,
        uint dwSize,
        uint flAllocationType,
        uint flProtect
        );

## Align Attribute

    AlignAttribute:
        align
        align ( IntegerLiteral )

Specifies the alignment of struct members. align by itself sets it to the default, which matches the default member alignment of the companion C compiler. Integer specifies the alignment which matches the behavior of the companion C compiler when non-default alignments are used.

Matching the behavior of the companion C compiler can have some surprising results, such as the following for Digital Mars C++:

    struct S {
      align(4) byte a; // placed at offset 0
      align(4) byte b; // placed at offset 1
    }

AlignAttribute is meant for C ABI compatiblity, which is not the same thing as binary compatibility across diverse platforms. For that, use packed structs:

    align (1) struct S {
      byte a;     // placed at offset 0
      byte[3] filler1;
      byte b;     // placed at offset 4
      byte[3] filler2;
    }

A value of 1 means that no alignment is done; members are packed together.

Do not align references or pointers that were allocated using NewExpression on boundaries that are not a multiple of `size_t`. The garbage collector assumes that pointers and references to gc allocated objects will be on `size_t` byte boundaries. If they are not, undefined behavior will result.

AlignAttribute is ignored when applied to declarations that are not struct members. Whether it applies to class members or not is implementation defined.

The AlignAttribute is reset to the default when entering a struct, union, class, or function scope, and restored when exiting that scope. It is not inherited from a base class.

## Deprecated Attribute

It is often necessary to deprecate a feature in a library, yet retain it for backwards compatibility. Such declarations can be marked as deprecated, which means that the compiler can be set to produce an error if any code refers to deprecated declarations:

    deprecated
    {
      void oldFoo();
    }

Implementation Note: The compiler should have a switch specifying if deprecated declarations should be compiled with out complaint or not.

## Protection Attribute

    ProtectionAttribute:
        private
        package
        protected
        public
        export

Protection is an attribute that is one of private, package, protected, public or export.

Private means that only members of the enclosing class can access the member, or members and functions in the same module as the enclosing class. Private members cannot be overridden. Private module members are equivalent to static declarations in C programs.

Package extends private so that package members can be accessed from code in other modules that are in the same package. This applies to the innermost package only, if a module is in nested packages.

Protected means that only members of the enclosing class or any classes derived from that class, or members and functions in the same module as the enclosing class, can access the member. If accessing a protected instance member through a derived class member function, that member can only be accessed for the object instance which can be implicitly cast to the same type as ‘this’. Protected module members are illegal.

Public means that any code within the executable can access the member.

Export means that any code outside the executable can access the member. Export is analogous to exporting definitions from a DLL.

## Const Attribute

The const attribute declares constants that can be evaluated at compile time. For example:

    const int foo = 7;

    const {
      double bar = foo + 6;
    }

## immutable Attribute

## __gshared Attribute

By default, non-immutable global declarations reside in thread local storage. When a global variable is marked with the __gshared attribute, its value is shared across all threads.

    int foo;            // Each thread has its own exclusive copy of foo.
    __gshared int bar;  // bar is shared by all threads.

__gshared may also be applied to member variables and local variables. In these cases, __gshared is equivalent to static, except that the variable is shared by all threads rather than being thread local.

    class Foo {
      __gshared int bar;
    }

    int foo() {
      __gshared int bar = 0;
      return bar++; // Not thread safe.
    }

Unlike the shared attribute, __gshared provides no safe-guards against data races or other multi-threaded synchronization issues. It is the responsibility of the programmer to ensure that access to variables marked __gshared is synchronized correctly.

__gshared is disallowed in safe mode.

## shared Attribute

## inout Attribute

## @disable Attribute

A reference to a declaration marked with the `@disable` attribute causes a compile time error. This can be used to explicitly disallow certain operations or overloads at compile time rather than relying on generating a runtime error.

    struct T {
      @disable this(this) { } // disabling this makes T not copyable
    }

    struct S {
      T t;   // uncopyable member makes S also not copyable
    }

    @disable void foo() { }

    void main() {
      S s;
      S t = s; // error, S is not copyable
      foo();   // error, foo is disabled
    }

## Override Attribute

The override attribute applies to virtual functions. It means that the function must override a function with the same name and parameters in a base class. The override attribute is useful for catching errors when a base class's member function gets its parameters changed, and all derived classes need to have their overriding functions updated.

    class Foo {
      int bar();
      int abc(int x);
    }

    class Foo2 : Foo {
      override {
        int bar(char c); // error, no bar(char) in Foo
        int abc(int x);  // ok
      }
    }

## Static Attribute

The static attribute applies to functions and data. It means that the declaration does not apply to a particular instance of an object, but to the type of the object. In other words, it means there is no this reference. static is ignored when applied to other declarations.

    class Foo {
      static int bar() { return 6; }
      int foobar() { return 7; }
    }

    ...

    Foo f = new Foo;
    Foo.bar();      // produces 6
    Foo.foobar();   // error, no instance of Foo
    f.bar();        // produces 6;
    f.foobar();     // produces 7;

Static functions are never virtual.

Static data has only one instance for the entire program, not once per object.

Static does not have the additional C meaning of being local to a file. Use the private attribute in D to achieve that. For example:

    module foo;
    int x = 3;         // x is global
    private int y = 4; // y is local to module foo

## Auto Attribute

The auto attribute is used when there are no other attributes and type inference is desired.

    auto i = 6.8;   // declare i as a double

## Scope Attribute

The scope attribute is used for local variables and for class declarations. For class declarations, the scope attribute creates a scope class. For local declarations, scope implements the RAII (Resource Acquisition Is Initialization) protocol. This means that the destructor for an object is automatically called when the reference to it goes out of scope. The destructor is called even if the scope is exited via a thrown exception, thus scope is used to guarantee cleanup.

If there is more than one scope variable going out of scope at the same point, then the destructors are called in the reverse order that the variables were constructed.

scope cannot be applied to globals, statics, data members, ref or out parameters. Arrays of scopes are not allowed, and scope function return values are not allowed. Assignment to a scope, other than initialization, is not allowed. Rationale: These restrictions may get relaxed in the future if a compelling reason to appears.

## Abstract Attribute

If a class is abstract, it cannot be instantiated directly. It can only be instantiated as a base class of another, non-abstract, class.

Classes become abstract if they are defined within an abstract attribute, or if any of the virtual member functions within it are declared as abstract.

Non-virtual functions cannot be declared as abstract.

Functions declared as abstract can still have function bodies. This is so that even though they must be overridden, they can still provide ‘base class functionality.’

Forums | Comments | D | Search | Downloads | Home
Copyright © 1999-2012 by Digital Mars ®, All Rights Reserved | Page generated by Ddoc.