//
// NAME
//      EngineServices.java
//
// COPYRIGHT
//      Confidential Property of Kabira Technologies, Inc.
//      Copyright 2007, 2009 by Kabira Technologies, Inc.
//      All rights reserved.
//
// DESCRIPTION
//
// HISTORY
//     $Revision: 1.1.2.83 $ $Date: 2012/04/03 00:11:05 $
//
// WARNINGS
//      THIS FILE IS GENERATED, DO NOT EDIT
//

package com.kabira.platform.swbuiltin;

import java.util.*;
import com.kabira.platform.annotation.*;


/**
<p>
       Engine services
<p>
       Provides access to engine level services.
                A transaction is required access this class.


*/

public final class EngineServices extends java.lang.Object
{
        private static final String _RuntimeType = "swbuiltin::EngineServices";
        /**
        <p>
       Throttle state

        */
        public enum ThrottleState
        {
                /**
                
                                Memory utilization below throttle level.  
                                System not congested.
                        
                */
                Clear,
                /**
                
                                Memory utilization above throttle level.
                                System is becoming congested.  Throttle
                                operation will block for a period of time
                                to allow congestion to clear.
                        
                */
                Throttled,
                /**
                
                                Memory utilization critical.  Application 
                                should stop accepting incoming work and 
                                attempt to free shared memory by processing
                                in-flight work.  In general if a system
                                ever hits Stall, shared memory size should
                                be increased since this system is 
                                misconfigured for the current load.
                        
                */
                Stall;
        
                private static ThrottleState from_ordinal(int ordinal)
                {
                        return ThrottleState.class.getEnumConstants()[ordinal];
                }
        }

        private EngineServices() { }


        /**
        <p>
       Determine if engine is shutting down
@return                true if engine is exiting,
                false otherwise

<p>
        This operation can be used to determine if
        the engine is currently being shut down.
        When an engine is being shutdown, this
        operation will return true to indicate that
        a spawned thread or dispatched operation
        should stop execution. If a thread does not
        use this operation to determine when it
        should exit, the engine will hang and
        eventually it will be killed by the
        coordinator causing a non-recoverable
        node failure.


        */

        public static final native boolean isStopping();


        /**
        <p>
       Schedule the current engine to exit
@param returnCode        Return value for engine
<p>
        This operation is used to schedule the exit
        of an engine.  This operation only schedules
        the engine to exit at some later time.  It 
        returns to the caller immediately.
<p>
        A non-zero returnCode value will cause the
        coordinator to mark node as failed and
        remove the node's shared memory upon restart.
<p>
        The node is marked failed if the
        engine does not exit within the configured
        engine abort timer after calling stop.


        */

        public static final native void stop(
                        final int returnCode);


        /**
        <p>
       Get the name of this engine.
@return                The name of this engine.

        */

        public static final native String getEngineName();


        /**
        <p>
       Node name for shared memory
@return                The node name of the shared memory
<p>
        Get the node name associated with the
        shared memory that this engine is running
        against.


        */

        public static final native String getNodeName();


        /**
        <p>
       Access engine instance
@return                The engine instance
<p>
        Get the engine instance for the engine.
        All engines on a node have a unique
        engine instance number.


        */

        public static final native int getEngineInstance();


        /**
        <p>
       Throttle incoming work if necessary
@return                Current throttle state
<p>
        If the percentage of shared memory in use
        exceeds the configured throttle threshold 
        (50% by default), the throttle operation will
        block a little to slow down incoming work. 
        Throttled is returned from the operation
        when in this state.  When shared memory 
        utilization becomes critical (80% by default)
        Stall is returned from the throttle operation
        after blocking for a longer period of time.
        The application should stop accepting
        incoming work at this point and attempt
        to complete processing already accepted
        work to clear shared memory space.


        */

        public static final native com.kabira.platform.swbuiltin.EngineServices.ThrottleState throttle();


        /**
        <p>
       Check the state of throttling
@return                Current throttle state
<p>
       Get the current throttle state.

        */

        public static final native com.kabira.platform.swbuiltin.EngineServices.ThrottleState getThrottleState();

}