/*
 * Copyright (c) 2011-2019 Contributors to the Eclipse Foundation
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
 * which is available at https://www.apache.org/licenses/LICENSE-2.0.
 *
 * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
 */

package io.vertx.core.impl;

import io.netty.channel.EventLoop;
import io.netty.util.concurrent.FastThreadLocalThread;
import io.vertx.core.*;
import io.vertx.core.impl.future.PromiseInternal;
import io.vertx.core.spi.tracing.VertxTracer;

import java.util.concurrent.ConcurrentMap;

This interface provides an api for vert.x core internal use only
It is not part of the public API and should not be used by
developers creating vert.x applications
Author:
Julien Viet/**
 * This interface provides an api for vert.x core internal use only
 * It is not part of the public API and should not be used by
 * developers creating vert.x applications
 *
 * @author <a href="mailto:julien@julienviet.com">Julien Viet</a>
 */
public interface ContextInternal extends Context {

  
Returns:
the current context/**
   * @return the current context
   */
  static ContextInternal current() {
    Thread current = Thread.currentThread();
    if (current instanceof VertxThread) {
      return ((VertxThread) current).context();
    }
    return null;
  }

  
Return the Netty EventLoop used by this Context. This can be used to integrate
a Netty Server with a Vert.x runtime, specially the Context part.
Returns:
the EventLoop/**
   * Return the Netty EventLoop used by this Context. This can be used to integrate
   * a Netty Server with a Vert.x runtime, specially the Context part.
   *
   * @return the EventLoop
   */
  EventLoop nettyEventLoop();

  
Returns:
a Promise associated with this context/**
   * @return a {@link Promise} associated with this context
   */
  <T> PromiseInternal<T> promise();

  
Returns:
a Promise associated with this context or the handler if that handler is already an instance of PromiseInternal/**
   * @return a {@link Promise} associated with this context or the {@code handler}
   *         if that handler is already an instance of {@code PromiseInternal}
   */
  <T> PromiseInternal<T> promise(Handler<AsyncResult<T>> handler);

  
Returns:
an empty succeeded Future associated with this context/**
   * @return an empty succeeded {@link Future} associated with this context
   */
  <T> Future<T> succeededFuture();

  
Returns:
a succeeded Future of the result associated with this context/**
   * @return a succeeded {@link Future} of the {@code result} associated with this context
   */
  <T> Future<T> succeededFuture(T result);

  
Returns:
a Future failed with the failure associated with this context/**
   * @return a {@link Future} failed with the {@code failure} associated with this context
   */
  <T> Future<T> failedFuture(Throwable failure);

  
Returns:
a Future failed with the message associated with this context/**
   * @return a {@link Future} failed with the {@code message} associated with this context
   */
  <T> Future<T> failedFuture(String message);

  
Like Context.executeBlocking(Handler<Promise<Object>>, boolean, Handler<AsyncResult<Object>>) but uses the queue to order the tasks instead of the internal queue of this context. /**
   * Like {@link #executeBlocking(Handler, boolean, Handler)} but uses the {@code queue} to order the tasks instead
   * of the internal queue of this context.
   */
  <T> void executeBlocking(Handler<Promise<T>> blockingCodeHandler, TaskQueue queue, Handler<AsyncResult<T>> resultHandler);

  
Like Context.executeBlocking(Handler<Promise<Object>>, boolean) but uses the queue to order the tasks instead of the internal queue of this context. /**
   * Like {@link #executeBlocking(Handler, boolean)} but uses the {@code queue} to order the tasks instead
   * of the internal queue of this context.
   */
  <T> Future<T> executeBlocking(Handler<Promise<T>> blockingCodeHandler, TaskQueue queue);

  
Execute an internal task on the internal blocking ordered executor.
/**
   * Execute an internal task on the internal blocking ordered executor.
   */
  <T> void executeBlockingInternal(Handler<Promise<T>> action, Handler<AsyncResult<T>> resultHandler);

  <T> void executeBlockingInternal(Handler<Promise<T>> action, boolean ordered, Handler<AsyncResult<T>> resultHandler);

  
Like executeBlockingInternal(Handler<Promise<Object>>, Handler<AsyncResult<Object>>) but returns a Future of the asynchronous result /**
   * Like {@link #executeBlockingInternal(Handler, Handler)} but returns a {@code Future} of the asynchronous result
   */
  <T> Future<T> executeBlockingInternal(Handler<Promise<T>> action);

  
Like executeBlockingInternal(Handler<Promise<Object>>, boolean, Handler<AsyncResult<Object>>) but returns a Future of the asynchronous result /**
   * Like {@link #executeBlockingInternal(Handler, boolean, Handler)} but returns a {@code Future} of the asynchronous result
   */
  <T> Future<T> executeBlockingInternal(Handler<Promise<T>> action, boolean ordered);

  
Returns:
the deployment associated with this context or null/**
   * @return the deployment associated with this context or {@code null}
   */
  Deployment getDeployment();

  @Override
  VertxInternal owner();

  
Emit the given argument event to the task and switch on this context if necessary, this also associates the current thread with the current context so Vertx.currentContext() returns this context. 
 Any exception thrown from the task will be reported on this context. 
 Calling this method is equivalent to execute(v -> dispatch(argument, task)) 
Params:
argument – the task argument
task – the handler to execute with the event argument/**
   * Emit the given {@code argument} event to the {@code task} and switch on this context if necessary, this also associates the
   * current thread with the current context so {@link Vertx#currentContext()} returns this context.
   * <br/>
   * Any exception thrown from the {@literal task} will be reported on this context.
   * <br/>
   * Calling this method is equivalent to {@code execute(v -> dispatch(argument, task))}
   *
   * @param argument the {@code task} argument
   * @param task the handler to execute with the {@code event} argument
   */
  <T> void emit(T argument, Handler<T> task);

  
See Also:
emit(Object, Handler)/**
   * @see #emit(Object, Handler)
   */
  void emit(Handler<Void> task);

  
See Also:
execute(Object, Handler)/**
   * @see #execute(Object, Handler)
   */
  void execute(Handler<Void> task);

  
Execute the task on this context, it will be executed according to the context concurrency model. 
Params:
task – the task to execute/**
   * Execute the {@code task} on this context, it will be executed according to the
   * context concurrency model.
   *
   * @param task the task to execute
   */
  void execute(Runnable task);

  
Execute a task on this context, the task will be executed according to the context concurrency model. 
Params:
argument – the task argument
task – the task to execute/**
   * Execute a {@code task} on this context, the task will be executed according to the
   * context concurrency model.
   *
   * @param argument the {@code task} argument
   * @param task the task to execute
   */
  <T> void execute(T argument, Handler<T> task);

  
Returns:
whether the current thread is running on this context/**
   * @return whether the current thread is running on this context
   */
  boolean isRunningOnContext();

  
See Also:
dispatch(Handler)/**
   * @see #dispatch(Handler)
   */
  void dispatch(Runnable handler);

  
See Also:
dispatch(Object, Handler)/**
   * @see #dispatch(Object, Handler)
   */
  void dispatch(Handler<Void> handler);

  
Dispatch an event to the handler on this context. 
 The handler is executed directly by the caller thread which must be a VertxThread or a FastThreadLocalThread. 

The handler execution is monitored by the blocked thread checker.

This context is thread-local associated during the task execution.
Params:
event – the event for the handler
handler – the handler to execute with the event/**
   * Dispatch an {@code event} to the {@code handler} on this context.
   * <p>
   * The handler is executed directly by the caller thread which must be a {@link VertxThread} or a {@link FastThreadLocalThread}.
   * <p>
   * The handler execution is monitored by the blocked thread checker.
   * <p>
   * This context is thread-local associated during the task execution.
   *
   * @param event the event for the {@code handler}
   * @param handler the handler to execute with the {@code event}
   */
  <E> void dispatch(E event, Handler<E> handler);

  
Begin the execution of a task on this context.

The task execution is monitored by the blocked thread checker.

This context is thread-local associated during the task execution.
 You should not use this API directly, instead you should use dispatch(Object, Handler<Object>) 
Throws:
IllegalStateException – when the current thread of execution cannot execute this task
Returns:
the previous context that shall be restored after or null if there is none/**
   * Begin the execution of a task on this context.
   * <p>
   * The task execution is monitored by the blocked thread checker.
   * <p>
   * This context is thread-local associated during the task execution.
   * <p>
   * You should not use this API directly, instead you should use {@link #dispatch(Object, Handler)}
   *
   * @return the previous context that shall be restored after or {@code null} if there is none
   * @throws IllegalStateException when the current thread of execution cannot execute this task
   */
  ContextInternal beginDispatch();

  
End the execution of a task on this context, see beginDispatch() 
 You should not use this API directly, instead you should use dispatch(Object, Handler<Object>) 
Params:
previous – the previous context to restore or null if there is none
Throws:
IllegalStateException – when the current thread of execution cannot execute this task/**
   * End the execution of a task on this context, see {@link #beginDispatch()}
   * <p>
   * You should not use this API directly, instead you should use {@link #dispatch(Object, Handler)}
   *
   * @param previous the previous context to restore or {@code null} if there is none
   * @throws IllegalStateException when the current thread of execution cannot execute this task
   */
  void endDispatch(ContextInternal previous);

  
Report an exception to this context synchronously.

The exception handler will be called when there is one, otherwise the exception will be logged.
Params:
t – the exception to report/**
   * Report an exception to this context synchronously.
   * <p>
   * The exception handler will be called when there is one, otherwise the exception will be logged.
   *
   * @param t the exception to report
   */
  void reportException(Throwable t);

  
See Also:
Context.get(String)
Context.put(String, Object)
Returns:
the ConcurrentMap used to store context data/**
   * @return the {@link ConcurrentMap} used to store context data
   * @see Context#get(String)
   * @see Context#put(String, Object)
   */
  ConcurrentMap<Object, Object> contextData();

  
Returns:
the ConcurrentMap used to store local context data/**
   * @return the {@link ConcurrentMap} used to store local context data
   */
  ConcurrentMap<Object, Object> localContextData();

  
Returns:
the classloader associated with this context/**
   * @return the classloader associated with this context
   */
  ClassLoader classLoader();

  
Returns:
the context worker pool/**
   * @return the context worker pool
   */
  WorkerPool workerPool();

  
Returns:
the tracer for this context/**
   * @return the tracer for this context
   */
  VertxTracer tracer();

  
Returns a context sharing with this context

  
the same concurrency
  
the same exception handler
  
the same context data
  
the same deployment
  
the same config
  
the same classloader


The duplicate context has its own

  
local context data
  
worker task queue

Returns:
a duplicate of this context/**
   * Returns a context sharing with this context
   * <ul>
   *   <li>the same concurrency</li>
   *   <li>the same exception handler</li>
   *   <li>the same context data</li>
   *   <li>the same deployment</li>
   *   <li>the same config</li>
   *   <li>the same classloader</li>
   * </ul>
   * <p>
   * The duplicate context has its own
   * <ul>
   *   <li>local context data</li>
   *   <li>worker task queue</li>
   * </ul>
   *
   * @return a duplicate of this context
   */
  ContextInternal duplicate();

  
Like Vertx.setPeriodic(long, Handler<Long>) except the periodic timer will fire on this context. /**
   * Like {@link Vertx#setPeriodic(long, Handler)} except the periodic timer will fire on this context.
   */
  long setPeriodic(long delay, Handler<Long> handler);

  
Like Vertx.setTimer(long, Handler<Long>) except the timer will fire on this context. /**
   * Like {@link Vertx#setTimer(long, Handler)} except the timer will fire on this context.
   */
  long setTimer(long delay, Handler<Long> handler);

  
Returns:
true when the context is associated with a deployment/**
   * @return {@code true} when the context is associated with a deployment
   */
  boolean isDeployment();

  
Add a close hook.
 The hook will be called when the associated resource needs to be released. Hooks are useful for automatically cleanup resources when a Verticle is undeployed. 
Params:
hook – the close hook/**
   * Add a close hook.
   *
   * <p> The {@code hook} will be called when the associated resource needs to be released. Hooks are useful
   * for automatically cleanup resources when a Verticle is undeployed.
   *
   * @param hook the close hook
   */
  void addCloseHook(Closeable hook);

  
Remove a close hook.
 This is called when the resource is released explicitly and does not need anymore a managed close.
Params:
hook – the close hook/**
   * Remove a close hook.
   *
   * <p> This is called when the resource is released explicitly and does not need anymore a managed close.
   *
   * @param hook the close hook
   */
  void removeCloseHook(Closeable hook);

}