Slice Metadata Directives

Overview

Slice has the concept of a metadata directive. For example:

["java:type:java.util.LinkedList<Integer>"] sequence<int> IntSeq;

A metadata directive can appear as a prefix to any Slice definition. Metadata directives appear in a pair of square brackets and contain one or more string literals separated by commas. For example, the following is a syntactically valid metadata directive containing two strings:

["a", "b"] interface Example {}

Metadata directives are not part of the Slice language per se: the presence of a metadata directive has no effect on the client-server contract, that is, metadata directives do not change the Slice type system in any way. Instead, metadata directives are targeted at specific back-ends, such as the code generator for a particular language mapping. In the preceding example, the java: prefix indicates that the directive is targeted at the Slice to Java compiler.

Metadata directives permit you to provide supplementary information that does not change the Slice types being defined, but somehow influences how the compiler will generate code for these definitions. For example, a metadata directive java:type:java.util.LinkedList<T> instructs the Slice to Java compiler to map a sequence to a linked list instead of an array (which is the default).

Metadata directives are also used to create skeletons that support Asynchronous Method Dispatch (AMD) in some languages.

Apart from metadata directives that are attached to a specific definition, there are also file metadata directives. For example:

[["cpp:dll-export:WIDGET_API"]]

Note that a file metadata directive is enclosed by double square brackets, whereas a local metadata directive (one that is attached to a specific definition) is enclosed by single square brackets. File metadata directives are used to pass instructions that affect the entire Slice file. File metadata directives must precede any definitions in a file (but can appear following any #include directives).

We describe below the metadata directives you can use.

General Metadata Directives

amd

This directive applies to interfaces and operations. It enables code generation for asynchronous method dispatch. (See Operations for details).

deprecated[:message]
deprecate[:message]

This directive allows you to emit a deprecation warning for Slice constructs.

format

This directive defines the encoding format used for any classes or exceptions marshaled as the arguments or results of an operation. The tag can be applied to an interface, which affects all of its operations, or to individual operations. Legal values for the tag are format:sliced, format:compact, and format:default. A tag specified for an operation overrides any setting applied to its enclosing interface. The Ice.Default.SlicedFormat property defines the behavior when no tag is present.

marshaled-result

This directive applies to operations and changes the return type of mapped skeleton methods in C++, C#, and Java. It has no effect on the client-side mapping.

With this directive, the mapped skeleton method returns a “marshaled result” struct or class that marshals the return value and out parameters immediately in its constructor. This allows you to perform the marshaling in a thread-safe manner, typically while holding a mutex lock.

For example:

sequence<int> IntSeq;
sequence<IntSeq> IntIntSeq;
sequence<string> StringSeq;

class Grid
{
    StringSeq xLabels;
    StringSeq yLabels;
    IntIntSeq values;
}
  
interface GridIntf
{
   // We want to marshal the returned Grid object within a lock,
   // and return a consistent object not affected by concurrent calls to
   // clearValues.
   ["marshaled-result"] 
   ["cs:identifier:GetGrid"]
   Grid getGrid();
   
   void clearValues();
}

A marshaled-result instance is specific to a request. Do not cache a marshaled result and return it for another request.

suppress-warning

This file directive allows to suppress Slice compiler warnings. It applies to all definitions in the Slice file that includes this directive. If one or more categories are specified (for example "suppress-warning:invalid-metadata" or "suppress-warning:deprecated, invalid-metadata") only warnings matching these categories will be suppressed, otherwise all warnings are suppressed. The categories are described in the following table:

Language-Specific Metadata Directives

The metadata directives for Python uses the python prefix.

python:array.array

Instructs the Ice for Python runtime to unmarshal a sequence as a Python array.array type. This directive applies to integral built-in types. See Python mapping for sequences..

python:identifier:<identifier>

This directive applies to all Slice constructs, and instructs the Slice compiler to use the specified python-identifier.

For example:

enum Color
{
    ["python:identifier:RED"]
    Red,

    ["python:identifier:GREEN"]
    Green

    ["python:identifier:BLUE"]
    Blue
}

The python:identifierdirectives in this example ensures the enumerators Read, Green, and Blue are mapped to RED, GREEN, and BLUE, per Python’s usual conventions, instead of the default mapping (Red, Green, and Blue).

python:list

Instruct the Ice for Python runtime to unmarshal a sequence as a list.

python:memoryview:<factory>(:type-hint)

Instructs the Ice for Python runtime to unmarshal a sequence as a custom Python type created from a Python memoryview object. See Python mapping for sequences..

python:numpy.ndarray

Instructs the Ice for Python runtime to unmarshal a sequence as a Python numpy.ndarray type. This directive applies to integral built-in types. See Python mapping for sequences..

python:tuple

Instructs the Ice for Python runtime to unmarshal a sequence as a Python tuple.