ice35-slice 3.5.1-5.2 / usr / share / Ice-3.5.1 / slice / Ice / Instrumentation.ice

// **********************************************************************
//
// Copyright (c) 2003-2013 ZeroC, Inc. All rights reserved.
//
// This copy of Ice is licensed to you under the terms described in the
// ICE_LICENSE file included in this distribution.
//
// **********************************************************************

#pragma once

[["cpp:header-ext:h"]]

#include <Ice/EndpointF.ice>
#include <Ice/ConnectionF.ice>
#include <Ice/Current.ice>

module Ice
{

/**
 *
 * The Instrumentation local interfaces enable observing a number of
 * Ice core internal components (threads, connections, etc).
 *
 **/
module Instrumentation
{

/**
 *
 * The object observer interface used by instrumented objects to
 * notify the observer of their existence.
 *
 **/
local interface Observer
{
    /**
     *
     * This method is called when the instrumented object is created
     * or when the observer is attached to an existing object.
     * 
     **/
    void attach();

    /**
     *
     * This method is called when the instrumented object is destroyed
     * and as a result the observer detached from the object.
     *
     **/
    void detach();

    /**
     *
     * Notification of a failure.
     *
     * @param exceptionName The name of the exception.
     *
     **/
    void failed(string exceptionName);
};
 
/**
 *
 * The thread state enumeration keeps track of the different possible
 * states of Ice threads.
 *
 **/ 
local enum ThreadState
{
    /**
     *
     * The thread is idle.
     *
     **/
    ThreadStateIdle,

    /**
     *
     * The thread is in use performing reads or writes for Ice
     * connections. This state is only for threads from an Ice thread
     * pool.
     *
     **/
    ThreadStateInUseForIO,

    /**
     *
     * The thread is calling user code (servant implementation, AMI
     * callbacks). This state is only for threads from an Ice thread
     * pool. 
     *
     **/
    ThreadStateInUseForUser,

    /**
     *
     * The thread is performing other internal activities (DNS
     * lookups, timer callbacks, etc).
     *
     **/
    ThreadStateInUseForOther,
};

/**
 *
 * The thread observer interface to instrument Ice threads. This can
 * be threads from the Ice thread pool or utility threads used by the
 * Ice core.
 * 
 **/
local interface ThreadObserver extends Observer
{
    /**
     *
     * Notification of thread state change.
     *
     * @param oldState The previous thread state.
     *
     * @param newState The new thread state.
     *
     **/ 
    void stateChanged(ThreadState oldState, ThreadState newState);
};

/**
 *
 * The state of an Ice connection.
 *
 **/ 
local enum ConnectionState
{
    /**
     *
     * The connection is being validated.
     *
     **/ 
    ConnectionStateValidating,

    /**
     *
     * The connection is holding the reception of new messages.
     *
     **/
    ConnectionStateHolding,
    
    /**
     *
     * The connection is active and can send and receive messages.
     *
     **/
    ConnectionStateActive,

    /**
     *
     * The connection is being gracefully shutdown and waits for the
     * peer to close its end of the connection.
     *
     **/
    ConnectionStateClosing,

    /**
     *
     * The connection is closed and waits for potential dispatch to be
     * finished before being destroyed and detached from the observer.
     *
     **/
    ConnectionStateClosed
};


/**
 *
 * The connection observer interface to instrument Ice connections.
 * 
 **/
local interface ConnectionObserver extends Observer
{
    /**
     *
     * Notification of sent bytes over the connection.
     *
     * @param num The number of bytes sent.
     * 
     **/
    void sentBytes(int num);

    /**
     *
     * Notification of received bytes over the connection.
     *
     * @param num The number of bytes received.
     * 
     **/
    void receivedBytes(int num);
};

/**
 *
 * The dispatch observer to instrument servant dispatch.
 *
 **/
local interface DispatchObserver extends Observer
{
    /**
     *
     * Notification of a user exception.
     *
     **/
    void userException();

    /**
     *
     * Reply notification.
     *
     * @param size The size of the reply.
     * 
     **/
    void reply(int size);
};

/**
 *
 * The remote invocation observer to instrument invocations that go
 * over the wire.
 *
 **/
local interface RemoteObserver extends Observer
{
    /**
     *
     * Reply notification.
     *
     * @param size The size of the reply.
     *
     **/
    void reply(int size);
};

/**
 *
 * The invocation observer to instrument invocations on proxies. A
 * proxy invocation can either result in a collocated or remote
 * invocation. If it results in a remote invocation, a sub-observer is
 * requested for the remote invocation.
 *
 **/
local interface InvocationObserver extends Observer
{
    /**
     *
     * Notification of the invocation being retried.
     *
     **/
    void retried();

    /**
     *
     * Notification of a user exception.
     *
     **/
    void userException();

    /**
     *
     * Get a remote observer for this invocation.
     *
     * @param con The connection information.
     *
     * @param endpt The connection endpoint.
     *
     * @param requestId The ID of the invocation.
     *
     * @param size The size of the invocation.
     *
     * @return The observer to instrument the remote invocation.
     *
     **/
    RemoteObserver getRemoteObserver(ConnectionInfo con, Endpoint endpt, int requestId, int size);
};

/**
 *
 * The observer updater interface. This interface is implemented by
 * the Ice run-time and an instance of this interface is provided by
 * the Ice communicator on initialization to the {@link
 * CommunicatorObserver} object set with the communicator
 * initialization data. The Ice communicator calls {@link
 * CommunicatorObserver#setObserverUpdater} to provide the observer
 * updater.
 *
 * This interface can be used by add-ins implementing the {@link
 * CommunicatorObserver} interface to update the observers of
 * connections and threads.
 *
 **/
local interface ObserverUpdater
{
    /**
     *
     * Update connection observers associated with each of the Ice
     * connection from the communicator and its object adapters.
     *
     * When called, this method goes through all the connections and
     * for each connection {@link CommunicatorObserver#getConnectionObserver}
     * is called. The implementation of getConnectionObserver has the
     * possibility to return an updated observer if necessary.
     * 
     **/
    void updateConnectionObservers();

    /**
     *
     * Update thread observers associated with each of the Ice thread
     * from the communicator and its object adapters.
     *
     * When called, this method goes through all the threads and for
     * each thread {@link CommunicatorObserver#getThreadObserver} is
     * called. The implementation of getThreadObserver has the
     * possibility to return an updated observer if necessary.
     * 
     **/
    void updateThreadObservers();
};

/**
 *
 * The communicator observer interface used by the Ice run-time to
 * obtain and update observers for its observable objects. This
 * interface should be implemented by add-ins that wish to observe Ice
 * objects in order to collect statistics. An instance of this
 * interface can be provided to the Ice run-time through the Ice
 * communicator initialization data.
 *
 **/
local interface CommunicatorObserver
{
    /**
     *
     * This method should return an observer for the given endpoint
     * information and connector. The Ice run-time calls this method
     * for each connection establishment attempt.
     *
     * @param endpt The endpoint.
     *
     * @param connector The description of the connector. For IP
     * transports, this is typically the IP address to connect to.
     *
     * @return The observer to instrument the connection establishment.
     *
     **/
    Observer getConnectionEstablishmentObserver(Endpoint endpt, string connector);

    /**
     *
     * This method should return an observer for the given endpoint
     * information. The Ice run-time calls this method to resolve an
     * endpoint and obtain the list of connectors. 
     *
     * For IP endpoints, this typically involves doing a DNS lookup to
     * obtain the IP addresses associated with the DNS name.
     *
     * @param endpt The endpoint.
     *
     * @return The observer to instrument the endpoint lookup.
     *
     **/
    Observer getEndpointLookupObserver(Endpoint endpt);

    /**
     * 
     * This method should return a connection observer for the given
     * connection. The Ice run-time calls this method for each new
     * connection and for all the Ice communicator connections when
     * {@link ObserverUpdater#updateConnections} is called.
     *
     * @param c The connection information.
     *
     * @param e The connection endpoint.
     *
     * @param s The state of the connection.
     *
     * @param o The old connection observer if one is already set or a
     * null reference otherwise.
     *
     * @return The connection observer to instrument the connection.
     *
     **/
    ConnectionObserver getConnectionObserver(ConnectionInfo c, Endpoint e, ConnectionState s, ConnectionObserver o);

    /**
     * 
     * This method should return a thread observer for the given
     * thread. The Ice run-time calls this method for each new thread
     * and for all the Ice communicator threads when
     * {@link ObserverUpdater#updateThreads} is called.
     *
     * @param parent The parent of the thread.
     *
     * @param id The ID of the thread to observe.
     *
     * @param s The state of the thread.
     *
     * @param o The old thread observer if one is already set or a
     * null reference otherwise.
     *
     * @return The thread observer to instrument the thread.
     *
     **/
    ThreadObserver getThreadObserver(string parent, string id, ThreadState s, ThreadObserver o);

    /**
     * 
     * This method should return an invocation observer for the given
     * invocation. The Ice run-time calls this method for each new
     * invocation on a proxy.
     *
     * @param prx The proxy used for the invocation.
     *
     * @param operation The name of the invocation.
     *
     * @param ctx The context specified by the user.
     *
     * @return The invocation observer to instrument the invocation.
     *
     **/
    InvocationObserver getInvocationObserver(Object* prx, string operation, Context ctx);

    /**
     * 
     * This method should return a dispatch observer for the given
     * dispatch. The Ice run-time calls this method each time it
     * receives an incoming invocation to be dispatched for an Ice
     * object.
     *
     * @param c The current object as provided to the Ice servant
     * dispatching the invocation.
     *
     * @param size The size of the dispatch.
     *
     * @return The dispatch observer to instrument the dispatch.
     *
     **/
    DispatchObserver getDispatchObserver(Current c, int size); 

    /**
     *
     * The Ice run-time calls this method when the communicator is
     * initialized. The add-in implementing this interface can use
     * this object to get the Ice run-time to re-obtain observers for
     * observed objects.
     *
     * @param updater The observer updater object.
     *
     **/
    void setObserverUpdater(ObserverUpdater updater);
};

};
    
};