= Vert.x Core Manual
:toc: left

At the heart of Vert.x is a set of Java APIs that we call *Vert.x Core*

https://github.com/eclipse/vert.x[Repository].

Vert.x core provides functionality for things like:

* Writing TCP clients and servers
* Writing HTTP clients and servers including support for WebSockets
* The Event bus
* Shared data - local maps and clustered distributed maps
* Periodic and delayed actions
* Deploying and undeploying Verticles
* Datagram Sockets
* DNS client
* File system access
* Virtual threads
* High availability
* Native transports
* Clustering

The functionality in core is fairly low level - you won't find stuff like database access, authorisation or high level
web functionality here - that kind of stuff you'll find in *Vert.x ext* (extensions).

Vert.x core is small and lightweight. You just use the parts you want. It's also entirely embeddable in your
existing applications - we don't force you to structure your applications in a special way just so you can use
Vert.x.

You can use core from any of the other languages that Vert.x supports. But here's a cool bit - we don't force
you to use the Java API directly from, say, JavaScript or Ruby - after all, different languages have different conventions
and idioms, and it would be odd to force Java idioms on Ruby developers (for example).
Instead, we automatically generate an *idiomatic* equivalent of the core Java APIs for each language.

From now on we'll just use the word *core* to refer to Vert.x core.

If you are using Maven or Gradle, add the following dependency to the _dependencies_ section of your
project descriptor to access the Vert.x Core API:

* Maven (in your `pom.xml`):

[source,xml,subs="+attributes"]
----
<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-core</artifactId>
  <version>5.0.0.CR1</version>
</dependency>
----

* Gradle (in your `build.gradle` file):

[source,groovy,subs="+attributes"]
----
dependencies {
  compile 'io.vertx:vertx-core:5.0.0.CR1'
}
----

Let's discuss the different concepts and features in core.

== In the beginning there was Vert.x

You can't do much in Vert.x-land unless you can communicate with a `link:../../apidocs/io/vertx/core/Vertx.html[Vertx]` object!

It's the control centre of Vert.x and is how you do pretty much everything, including creating clients and servers,
getting a reference to the event bus, setting timers, as well as many other things.

So how do you get an instance?

If you're embedding Vert.x then you simply create an instance as follows:

[source,java]
----
Vertx vertx = Vertx.vertx();
----

NOTE: Most applications will only need a single Vert.x instance, but it's possible to create multiple Vert.x instances if you
require, for example, isolation between the event bus or different groups of servers and clients.

=== Specifying options when creating a Vertx object

When creating a Vert.x object you can also specify options if the defaults aren't right for you:

[source,java]
----
Vertx vertx = Vertx.vertx(new VertxOptions().setWorkerPoolSize(40));
----

The `link:../../apidocs/io/vertx/core/VertxOptions.html[VertxOptions]` object has many settings and allows you to configure things like clustering, high availability, pool sizes and various other settings.

=== Creating a clustered Vert.x object

If you're creating a *clustered Vert.x* (See the section on the <<event_bus, event bus>> for more information on clustering the event bus),
then you will normally use the asynchronous variant to create the Vertx object.

This is because it usually takes some time (maybe a few seconds) for the different Vert.x instances in a cluster to group together.
During that time, we don't want to block the calling thread, so we give the result to you asynchronously.

== Are you fluent?

You may have noticed that in the previous examples a *fluent* API was used.

A fluent API is where multiple methods calls can be chained together. For example:

[source,java]
----
request.response().putHeader("Content-Type", "text/plain").end("some text");
----

This is a common pattern throughout Vert.x APIs, so get used to it.

Chaining calls like this allows you to write code that's a little bit less verbose. Of course, if you don't
like the fluent approach *we don't force you* to do it that way, you can happily ignore it if you prefer and write
your code like this:

[source,java]
----
HttpServerResponse response = request.response();
response.putHeader("Content-Type", "text/plain");
response.end("some text");
----

== Don't call us, we'll call you.

The Vert.x APIs are largely _event driven_. This means that when things happen in Vert.x that you are interested in,
Vert.x will call you by sending you events.

Some example events are:

* a timer has fired
* some data has arrived on a socket,
* some data has been read from disk
* an exception has occurred
* an HTTP server has received a request

You handle events by providing _handlers_ to the Vert.x APIs. For example to receive a timer event every second you
would do:

[source,java]
----
vertx.setPeriodic(1000, id -> {
  // This handler will get called every second
  System.out.println("timer fired!");
});
----

Or to receive an HTTP request:

[source,java]
----
server.requestHandler(request -> {
  // This handler will be called every time an HTTP request is received at the server
  request.response().end("hello world!");
});
----

Some time later when Vert.x has an event to pass to your handler Vert.x will call it *asynchronously*.

This leads us to some important concepts in Vert.x:

== Don't block me!

With very few exceptions (i.e. some file system operations ending in 'Sync'), none of the APIs in Vert.x block the calling thread.

If a result can be provided immediately, it will be returned immediately, otherwise you will usually provide a handler
to receive events some time later.

Because none of the Vert.x APIs block threads that means you can use Vert.x to handle a lot of concurrency using
just a small number of threads.

With a conventional blocking API the calling thread might block when:

* Reading data from a socket
* Writing data to disk
* Sending a message to a recipient and waiting for a reply.
* ... Many other situations

In all the above cases, when your thread is waiting for a result it can't do anything else - it's effectively useless.

This means that if you want a lot of concurrency using blocking APIs then you need a lot of threads to prevent your
application grinding to a halt.

Threads have overhead in terms of the memory they require (e.g. for their stack) and in context switching.

For the levels of concurrency required in many modern applications, a blocking approach just doesn't scale.

== Reactor and Multi-Reactor

We mentioned before that Vert.x APIs are event driven - Vert.x passes events to handlers when they are available.

In most cases Vert.x calls your handlers using a thread called an *event loop*.

As nothing in Vert.x or your application blocks, the event loop can merrily run around delivering events to different handlers in succession
as they arrive.

Because nothing blocks, an event loop can potentially deliver huge amounts of events in a short amount of time.
For example a single event loop can handle many thousands of HTTP requests very quickly.

We call this the http://en.wikipedia.org/wiki/Reactor_pattern[Reactor Pattern].

You may have heard of this before - for example Node.js implements this pattern.

In a standard reactor implementation there is a *single event loop* thread which runs around in a loop delivering all
events to all handlers as they arrive.

The trouble with a single thread is it can only run on a single core at any one time, so if you want your single threaded
reactor application (e.g. your Node.js application) to scale over your multi-core server you have to start up and
manage many different processes.

Vert.x works differently here. Instead of a single event loop, each Vertx instance maintains *several event loops*.
By default we choose the number based on the number of available cores on the machine, but this can be overridden.

This means a single Vertx process can scale across your server, unlike Node.js.

We call this pattern the *Multi-Reactor Pattern* to distinguish it from the single threaded reactor pattern.

NOTE: Even though a Vertx instance maintains multiple event loops, any particular handler will never be executed
concurrently, and in most cases (with the exception of <<worker_verticles, worker verticles>>) will always be called
using the *exact same event loop*.

[[golden_rule]]
== The Golden Rule - Don't Block the Event Loop

We already know that the Vert.x APIs are non blocking and won't block the event loop, but that's not much help if
you block the event loop *yourself* in a handler.

If you do that, then that event loop will not be able to do anything else while it's blocked. If you block all of the
event loops in Vertx instance then your application will grind to a complete halt!

So don't do it! *You have been warned*.

Examples of blocking include:

* +Thread.sleep()+
* Waiting on a lock
* Waiting on a mutex or monitor (e.g. synchronized section)
* Doing a long lived database operation and waiting for a result
* Doing a complex calculation that takes some significant time.
* Spinning in a loop

If any of the above stop the event loop from doing anything else for a *significant amount of time* then you should
go immediately to the naughty step, and await further instructions.

So... what is a *significant amount of time*?

How long is a piece of string? It really depends on your application and the amount of concurrency you require.

If you have a single event loop, and you want to handle 10000 http requests per second, then it's clear that each request
can't take more than 0.1 ms to process, so you can't block for any more time than that.

*The maths is not hard and shall be left as an exercise for the reader.*

If your application is not responsive it might be a sign that you are blocking an event loop somewhere. To help
you diagnose such issues, Vert.x will automatically log warnings if it detects an event loop hasn't returned for
some time. If you see warnings like these in your logs, then you should investigate.

----
Thread vertx-eventloop-thread-3 has been blocked for 20458 ms
----

Vert.x will also provide stack traces to pinpoint exactly where the blocking is occurring.

If you want to turn off these warnings or change the settings, you can do that in the
`link:../../apidocs/io/vertx/core/VertxOptions.html[VertxOptions]` object before creating the Vertx object.

include::futures.adoc[]

== Verticles

Vert.x comes with a simple, scalable, _actor-like_ deployment and concurrency model out of the box that
you can use to save you writing your own.

*This model is entirely optional and Vert.x does not force you to create your applications in this way if you don't
want to.*.

The model does not claim to be a strict actor-model implementation, but it does share similarities especially
with respect to concurrency, scaling and deployment.

To use this model, you write your code as set of *verticles*.

Verticles are chunks of code that get deployed and run by Vert.x. A Vert.x instance maintains N event loop threads
(where N by default is core*2) by default. Verticles can be written in any of the languages that Vert.x supports
and a single application can include verticles written in multiple languages.

You can think of a verticle as a bit like an actor in the http://en.wikipedia.org/wiki/Actor_model[Actor Model].

An application would typically be composed of many verticle instances running in the same Vert.x instance at the same
time. The different verticle instances communicate with each other by sending messages on the <<event_bus, event bus>>.

=== Writing Verticles

Verticle classes must implement the `link:../../apidocs/io/vertx/core/Deployable.html[Deployable]` interface.

They can implement it directly if you like, but usually it's simpler to extend
the abstract class `link:../../apidocs/io/vertx/core/VerticleBase.html[VerticleBase]`.

Here's an example verticle:

[source,java]
----
class MyVerticle extends VerticleBase {

  // Called when verticle is deployed
  public Future<?> start() throws Exception {
    return super.start();
  }

  // Optional - called when verticle is un-deployed
  public Future<?> stop() throws Exception {
    return super.stop();
  }
}
----

Normally you would override the start method like in the example above.

When Vert.x deploys the verticle it will call the start method, and when future returned by the method has completed the verticle will
be considered started.

You can also optionally override the stop method. This will be called by Vert.x when the verticle is un-deployed and when
the future returned by the method has completed the verticle will be considered stopped.

Here's a more elaborated example:

[source,java]
----
class MyVerticle extends VerticleBase {

  private HttpServer server;

  @Override
  public Future<?> start() {
    server = vertx.createHttpServer().requestHandler(req -> {
      req.response()
        .putHeader("content-type", "text/plain")
        .end("Hello from Vert.x!");
    });

    // Now bind the server:
    return server.listen(8080);
  }
}
----

You can even write a one-liner Verticle:

[source,java]
----
Deployable verticle = context -> vertx
  .createHttpServer()
  .requestHandler(req -> req.response()
    .putHeader("content-type", "text/plain")
    .end("Hello from Vert.x!"))
  .listen(8080);
----

NOTE: You don't need to manually stop the HTTP server started by a verticle, in the verticle's stop method. Vert.x
will automatically stop any running server when the verticle is un-deployed.

=== What happened to Vert.x 4 Verticle and AbstractVerticle contracts?

The contract defined by `Verticle` and `AbstractVerticle` was not adapted anymore to Vert.x 5 future based model

[source,java]
----
class MyVerticle extends AbstractVerticle {
  @Override
  public void start(Promise<Void> startPromise) throws Exception {
    Future<String> future = bindService();

    // Requires to write
    future.onComplete(ar -> {
      if (ar.succeeded()) {
        startPromise.complete();
      } else {
        startPromise.fail(ar.cause());
      }
    });

    // Or
    future
      .<Void>mapEmpty()
      .onComplete(startPromise);
  }
}
----

`Verticle` and `AbstractVerticle` are not deprecated in Vert.x 5 and it is fine to use them, however it is not the default
recommended choice anymore.

=== Verticle Types

There are two different types of verticles:

Standard Verticles:: These are the most common and useful type - they are always executed using an event loop thread.
We'll discuss this more in the next section.
Worker Verticles:: These run using a thread from the worker pool. An instance is never executed concurrently by more
than one thread.

=== Standard verticles

Standard verticles are assigned an event loop thread when they are created and the +start+ method is called with that
event loop. When you call any other methods that takes a handler on a core API from an event loop then Vert.x
will guarantee that those handlers, when called, will be executed on the same event loop.

This means we can guarantee that all the code in your verticle instance is always executed on the same event loop (as
long as you don't create your own threads and call it!).

This means you can write all the code in your application as single threaded and let Vert.x worry about the threading
and scaling. No more worrying about +synchronized+ and +volatile+ any more, and you also avoid many other cases of race conditions
and deadlock so prevalent when doing hand-rolled 'traditional' multi-threaded application development.

[[worker_verticles]]
=== Worker verticles

A worker verticle is just like a standard verticle but it's executed using a thread from the Vert.x worker thread pool,
rather than using an event loop.

Worker verticles are designed for calling blocking code, as they won't block any event loops.

If you don't want to use a worker verticle to run blocking code, you can also run <<blocking_code, inline blocking code>>
directly while on an event loop.

If you want to deploy a verticle as a worker verticle you do that with `link:../../apidocs/io/vertx/core/DeploymentOptions.html#setThreadingModel-io.vertx.core.ThreadingModel-[setThreadingModel]`.

[source,java]
----
DeploymentOptions options = new DeploymentOptions().setThreadingModel(ThreadingModel.WORKER);
vertx.deployVerticle(new MyOrderProcessorVerticle(), options);
----

Worker verticle instances are never executed concurrently by Vert.x by more than one thread, but can executed by
different threads at different times.

=== Virtual thread verticles

A virtual thread verticle is just like a standard verticle but it's executed using virtual threads, rather than using an event loop.

Virtual thread verticles are designed to use an async/await model with Vert.x futures.

If you want to deploy a verticle as a <<virtual_threads, virtual thread verticle>> you do that with `link:../../apidocs/io/vertx/core/DeploymentOptions.html#setThreadingModel-io.vertx.core.ThreadingModel-[setThreadingModel]`.

[source,java]
----
DeploymentOptions options = new DeploymentOptions().setThreadingModel(ThreadingModel.VIRTUAL_THREAD);
vertx.deployVerticle(new MyOrderProcessorVerticle(), options);
----

NOTE: this feature requires Java 21

=== Deploying verticles programmatically

You can deploy a verticle using one of the `link:../../apidocs/io/vertx/core/Vertx.html#deployVerticle-io.vertx.core.Deployable-[deployVerticle]` method, specifying a verticle
name, or you can pass in a verticle instance you have already created yourself.

[source,java]
----
VerticleBase myVerticle = new MyVerticle();
vertx.deployVerticle(myVerticle);
----

You can also deploy verticles by specifying the verticle *name*.

The verticle name is used to look up the specific `link:../../apidocs/io/vertx/core/spi/VerticleFactory.html[VerticleFactory]` that will be used to
instantiate the actual verticle instance(s).

Here's an example of deploying some a Java Verticle using its class name:

[source,java]
----
vertx.deployVerticle("com.mycompany.MyOrderProcessorVerticle");
----

=== Rules for mapping a verticle name to a verticle factory

When deploying verticle(s) using a name, the name is used to select the actual verticle factory that will instantiate
the verticle(s).

Verticle names can have a prefix - which is a string followed by a colon, which when present will be used to lookup the factory, e.g.

[source]
----
 groovy:com.mycompany.SomeGroovyCompiledVerticle // Use the Groovy verticle factory
----

When prefix is absent, Vert.x will look for a suffix and use that to lookup the factory, e.g.

[source]
----
 SomeScript.groovy // Will use the Groovy verticle factory
----

If no prefix or suffix is present, Vert.x will assume it's a Java fully qualified class name (FQCN) and try
and instantiate that.

=== How are Verticle Factories located?

Most Verticle factories are loaded from the classpath and registered at Vert.x startup.

You can also programmatically register and unregister verticle factories using `link:../../apidocs/io/vertx/core/Vertx.html#registerVerticleFactory-io.vertx.core.spi.VerticleFactory-[registerVerticleFactory]`
and `link:../../apidocs/io/vertx/core/Vertx.html#unregisterVerticleFactory-io.vertx.core.spi.VerticleFactory-[unregisterVerticleFactory]` if you wish.

=== Waiting for deployment to complete

Verticle deployment is asynchronous and may complete some time after the call to deploy has returned.

If you want to be notified when deployment is complete you can deploy specifying a completion handler:

[source,java]
----
vertx
  .deployVerticle(new MyOrderProcessorVerticle())
  .onComplete(res -> {
    if (res.succeeded()) {
      System.out.println("Deployment id is: " + res.result());
    } else {
      System.out.println("Deployment failed!");
    }
  });
----

The completion handler will be passed a result containing the deployment ID string, if deployment succeeded.

This deployment ID can be used later if you want to undeploy the deployment.

=== Un-deploying verticle deployments

Deployments can be un-deployed with `link:../../apidocs/io/vertx/core/Vertx.html#undeploy-java.lang.String-[undeploy]`.

Un-deployment is itself asynchronous so if you want to be notified when un-deployment is complete you can deploy specifying a completion handler:

[source,java]
----
vertx
  .undeploy(deploymentID)
  .onComplete(res -> {
    if (res.succeeded()) {
      System.out.println("Undeployed ok");
    } else {
      System.out.println("Undeploy failed!");
    }
  });
----

=== Specifying number of verticle instances

When deploying a verticle using a verticle, you can specify the number of verticle instances that you
want to deploy, you also need to pass a `Callable<Deployable>` so Vert.x can instantiate your verticle
instances.

[source,java]
----
DeploymentOptions options = new DeploymentOptions().setInstances(16);
vertx.deployVerticle(() -> new MyOrderProcessorVerticle(), options);
----

This is useful for scaling easily across multiple cores. For example, you might have a web-server verticle to deploy
and multiple cores on your machine, so you want to deploy multiple instances to utilise all the cores.

=== Passing configuration to a verticle

Configuration in the form of JSON can be passed to a verticle at deployment time:

[source,java]
----
JsonObject config = new JsonObject().put("name", "tim").put("directory", "/blah");
DeploymentOptions options = new DeploymentOptions().setConfig(config);
vertx.deployVerticle(new MyOrderProcessorVerticle(), options);
----

This configuration is then available via the `link:../../apidocs/io/vertx/core/Context.html[Context]` object or directly using the
`link:../../apidocs/io/vertx/core/AbstractVerticle.html#config--[config]` method. The configuration is returned as a JSON object so you
can retrieve data as follows:

[source,java]
----
System.out.println("Configuration: " + config().getString("name"));
----

=== Accessing environment variables in a Verticle

Environment variables and system properties are accessible using the Java API:

[source,java]
----
System.getProperty("prop");
System.getenv("HOME");
----

=== Causing Vert.x to exit

Threads maintained by Vert.x instances are not daemon threads so they will prevent the JVM from exiting.

If you are embedding Vert.x and you have finished with it, you can call `link:../../apidocs/io/vertx/core/Vertx.html#close--[close]` to close it
down.

This will shut-down all internal thread pools and close other resources, and will allow the JVM to exit.

=== The Context object

When Vert.x provides an event to a handler or calls the start or stop methods of a
`link:../../apidocs/io/vertx/core/Verticle.html[Verticle]`, the execution is associated with a `Context`. Usually a context is an
*event-loop context* and is tied to a specific event loop thread. So executions for that context always occur
on that exact same event loop thread. In the case of worker verticles and running inline blocking code a
worker context will be associated with the execution which will use a thread from the worker thread pool.

To retrieve the context, use the `link:../../apidocs/io/vertx/core/Vertx.html#getOrCreateContext--[getOrCreateContext]` method:

[source, java]
----
Context context = vertx.getOrCreateContext();
----

If the current thread has a context associated with it, it reuses the context object. If not a new instance of
context is created. You can test the _type_ of context you have retrieved:

[source, java]
----
Context context = vertx.getOrCreateContext();
if (context.isEventLoopContext()) {
  System.out.println("Context attached to Event Loop");
} else if (context.isWorkerContext()) {
  System.out.println("Context attached to Worker Thread");
} else if (! Context.isOnVertxThread()) {
  System.out.println("Context not attached to a thread managed by vert.x");
}
----

When you have retrieved the context object, you can run code in this context asynchronously. In other words,
you submit a task that will be eventually run in the same context, but later:

[source, java]
----
vertx.getOrCreateContext().runOnContext( (v) -> {
  System.out.println("This will be executed asynchronously in the same context");
});
----

When several handlers run in the same context, they may want to share data. The context object offers methods to
store and retrieve data shared in the context. For instance, it lets you pass data to some action run with
`link:../../apidocs/io/vertx/core/Context.html#runOnContext-io.vertx.core.Handler-[runOnContext]`:

[source, java]
----
final Context context = vertx.getOrCreateContext();
context.put("data", "hello");
context.runOnContext((v) -> {
  String hello = context.get("data");
});
----

The context object also let you access verticle configuration using the `link:../../apidocs/io/vertx/core/Context.html#config--[config]`
method. Check the <<Passing configuration to a verticle>> section for more details about this configuration.

=== Executing periodic and delayed actions

It's very common in Vert.x to want to perform an action after a delay, or periodically.

In standard verticles you can't just make the thread sleep to introduce a delay, as that will block the event loop thread.

Instead you use Vert.x timers. Timers can be *one-shot* or *periodic*. We'll discuss both

==== One-shot Timers

A one shot timer calls an event handler after a certain delay, expressed in milliseconds.

To set a timer to fire once you use `link:../../apidocs/io/vertx/core/Vertx.html#setTimer-long-io.vertx.core.Handler-[setTimer]` method passing in the delay and a handler

[source,java]
----
long timerID = vertx.setTimer(1000, id -> {
  System.out.println("And one second later this is printed");
});

System.out.println("First this is printed");
----

The return value is a unique timer id which can later be used to cancel the timer. The handler is also passed the timer id.

==== Periodic Timers

You can also set a timer to fire periodically by using `link:../../apidocs/io/vertx/core/Vertx.html#setPeriodic-long-io.vertx.core.Handler-[setPeriodic]`.

There will be an initial delay equal to the period.

The return value of `setPeriodic` is a unique timer id (long). This can be later used if the timer needs to be cancelled.

The argument passed into the timer event handler is also the unique timer id:

Keep in mind that the timer will fire on a periodic basis. If your periodic treatment takes a long amount of time to proceed,
your timer events could run continuously or even worse : stack up.

In this case, you should consider using `link:../../apidocs/io/vertx/core/Vertx.html#setTimer-long-io.vertx.core.Handler-[setTimer]` instead. Once your treatment has
finished, you can set the next timer.

[source,java]
----
long timerID = vertx.setPeriodic(1000, id -> {
  System.out.println("And every second this is printed");
});

System.out.println("First this is printed");
----

==== Cancelling timers

To cancel a periodic timer, call `link:../../apidocs/io/vertx/core/Vertx.html#cancelTimer-long-[cancelTimer]` specifying the timer id. For example:

[source,java]
----
vertx.cancelTimer(timerID);
----

==== Automatic clean-up in verticles

If you're creating timers from inside verticles, those timers will be automatically closed
when the verticle is undeployed.

=== Verticle worker pool

Verticles use the Vert.x worker pool for executing blocking actions, i.e `link:../../apidocs/io/vertx/core/Context.html#executeBlocking-java.util.concurrent.Callable-boolean-[executeBlocking]` or
worker verticle.

A different worker pool can be specified in deployment options:

[source,java]
----
vertx.deployVerticle(new MyOrderProcessorVerticle(), new DeploymentOptions().setWorkerPoolName("the-specific-pool"));
----

[[event_bus]]
include::eventbus.adoc[]

include::json.adoc[]

include::json-pointers.adoc[]

include::buffers.adoc[]

include::net.adoc[]

include::http.adoc[]

include::shareddata.adoc[]

include::filesystem.adoc[]

include::datagrams.adoc[]

include::dns.adoc[]

[[virtual_threads]]
include::virtualthreads.adoc[]

[[streams]]
include::streams.adoc[]

include::parsetools.adoc[]

== Thread safety

Most Vert.x objects are safe to access from different threads. _However_ performance is optimised when they are
accessed from the same context they were created from.

For example if you have deployed a verticle which creates a `link:../../apidocs/io/vertx/core/net/NetServer.html[NetServer]` which provides
`link:../../apidocs/io/vertx/core/net/NetSocket.html[NetSocket]` instances in it's handler, then it's best to always access that socket instance
from the event loop of the verticle.

If you stick to the standard Vert.x verticle deployment model and avoid sharing objects between verticles then this
should be the case without you having to think about it.

[[blocking_code]]
== Running blocking code

In a perfect world, there will be no war or hunger, all APIs will be written asynchronously and bunny rabbits will
skip hand-in-hand with baby lambs across sunny green meadows.

*But... the real world is not like that. (Have you watched the news lately?)*

Fact is, many, if not most libraries, especially in the JVM ecosystem have synchronous APIs and many of the methods are
likely to block. A good example is the JDBC API - it's inherently synchronous, and no matter how hard it tries, Vert.x
cannot sprinkle magic pixie dust on it to make it asynchronous.

We're not going to rewrite everything to be asynchronous overnight so we need to provide you a way to use "traditional"
blocking APIs safely within a Vert.x application.

As discussed before, you can't call blocking operations directly from an event loop, as that would prevent it
from doing any other useful work. So how can you do this?

It's done by calling `link:../../apidocs/io/vertx/core/Vertx.html#executeBlocking-java.util.concurrent.Callable-boolean-[executeBlocking]` with blocking code to execute, as return you get a
future completed with the result of the blocking code execution.

[source,java]
----
vertx.executeBlocking(() -> {
  // Call some blocking API that takes a significant amount of time to return
  return someAPI.blockingMethod("hello");
}).onComplete(res -> {
  System.out.println("The result is: " + res.result());
});
----

WARNING: Blocking code should block for a reasonable amount of time (i.e no more than a few seconds). Long blocking operations
or polling operations (i.e a thread that spin in a loop polling events in a blocking fashion) are precluded.
When the blocking operation lasts more than the 10 seconds, a message will be printed on the console by the
blocked thread checker. Long blocking operations should use a dedicated thread managed by the application,
which can interact with verticles using the event-bus or `link:../../apidocs/io/vertx/core/Context.html#runOnContext-io.vertx.core.Handler-[runOnContext]`


By default, if executeBlocking is called several times from the same context (e.g. the same verticle instance) then
the different executeBlocking are executed _serially_ (i.e. one after another).

If you don't care about ordering you can call `link:../../apidocs/io/vertx/core/Vertx.html#executeBlocking-java.util.concurrent.Callable-boolean-[executeBlocking]`
specifying `false` as the argument to `ordered`. In this case any executeBlocking may be executed in parallel
on the worker pool.

An alternative way to run blocking code is to use a <<worker_verticles, worker verticle>>

A worker verticle is always executed with a thread from the worker pool.

By default blocking code is executed on the Vert.x worker pool, configured with `link:../../apidocs/io/vertx/core/VertxOptions.html#setWorkerPoolSize-int-[setWorkerPoolSize]`.

Additional pools can be created for different purposes:

[source,java]
----
WorkerExecutor executor = vertx.createSharedWorkerExecutor("my-worker-pool");
executor.executeBlocking(() -> {
  // Call some blocking API that takes a significant amount of time to return
  return someAPI.blockingMethod("hello");
}).onComplete(res -> {
  System.out.println("The result is: " + res.result());
});
----

The worker executor must be closed when it's not necessary anymore:

[source,java]
----
executor.close();
----

When several workers are created with the same name, they will share the same pool. The worker pool is destroyed
when all the worker executors using it are closed.

When an executor is created in a Verticle, Vert.x will close it automatically for you when the Verticle
is undeployed.

Worker executors can be configured when created:

[source,java]
----
int poolSize = 10;

// 2 minutes
long maxExecuteTime = 2;
TimeUnit maxExecuteTimeUnit = TimeUnit.MINUTES;

WorkerExecutor executor = vertx.createSharedWorkerExecutor("my-worker-pool", poolSize, maxExecuteTime, maxExecuteTimeUnit);
----

NOTE: the configuration is set when the worker pool is created

== Vert.x SPI

A Vert.x instance has a few extension points knows as _SPI_ (Service Provider Interface).

Such SPI are often loaded from the classpath using Java's `ServiceLoader` mechanism.

=== Metrics and tracing SPI

By default, Vert.x does not record any metrics nor does any tracing. Instead, it provides an SPI for others to implement which can be added
to the classpath. The metrics SPI is a feature which allows implementers to capture events from Vert.x in order to
collect and report metrics, likewise the tracing SPI does the same for traces.

For more information on this, please consult https://vertx.io/docs/#monitoring

=== Cluster Manager SPI

In Vert.x a cluster manager is used for various functions including:

* Discovery and group membership of Vert.x nodes in a cluster
* Maintaining cluster wide topic subscriber lists (so we know which nodes are interested in which event bus addresses)
* Distributed Map support
* Distributed Locks
* Distributed Counters

Cluster managers _do not_ handle the event bus inter-node transport, this is done directly by Vert.x with TCP connections.

The default cluster manager used in the Vert.x distributions is one that uses http://hazelcast.com[Hazelcast] but this
can be easily replaced by a different implementation as Vert.x cluster managers are pluggable.

A cluster manager must implement the interface `link:../../apidocs/io/vertx/core/spi/cluster/ClusterManager.html[ClusterManager]`. Vert.x locates
cluster managers at run-time by using the Java https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html[Service Loader] functionality to locate instances of `link:../../apidocs/io/vertx/core/spi/cluster/ClusterManager.html[ClusterManager]` on the classpath.

If you are using Vert.x at the command line and you want to use clustering you should make sure the `lib` directory
of the Vert.x installation contains your cluster manager jar.

If you are using Vert.x from a Maven or Gradle project just add the cluster manager jar as a dependency of your project.

For more information on this, please consult https://vertx.io/docs/#clustering

=== Programmatic SPI selection and configuration

The `link:../../apidocs/io/vertx/core/VertxBuilder.html[VertxBuilder]` gives you more control over the SPI selection and configuration.

[source,java]
----
Vertx vertx = Vertx.builder()
  .with(options)
  .withMetrics(metricsFactory)
  .build();
----

Clustered instances can also be created.

[source,java]
----
Future<Vertx> vertx = Vertx.builder()
  .with(options)
  .withClusterManager(clusterManager)
  .buildClustered();
----

== Logging

Vert.x logs using its internal logging API and supports various logging backends.

The logging backend is selected as follows:

. the backend denoted by the `vertx.logger-delegate-factory-class-name` system property if present or,
. JDK logging when a `vertx-default-jul-logging.properties` file is in the classpath or,
. a backend present in the classpath, in the following order of preference:
.. SLF4J
.. Log4J2

Otherwise Vert.x defaults to JDK logging.

=== Configuring with the system property

Set the `vertx.logger-delegate-factory-class-name` system property to:

* `io.vertx.core.logging.SLF4JLogDelegateFactory` for SLF4J or,
* `io.vertx.core.logging.Log4j2LogDelegateFactory` for Log4J2 or,
* `io.vertx.core.logging.JULLogDelegateFactory` for JDK logging

=== Automatic configuration

When no `vertx.logger-delegate-factory-class-name` system property is set, Vert.x will try to find
the most appropriate logger:

* use SLF4J when available on the classpath with an actual implementation (i.e. `LoggerFactory.getILoggerFactory()` is not an instance of `NOPLoggerFactory`)
* otherwise use Log4j2 when available on the classpath
* otherwise use JUL

=== Configuring JUL logging

A JUL logging configuration file can be specified in the normal JUL way, by providing a system property named `java.util.logging.config.file` with the value being your configuration file.
For more information on this and the structure of a JUL config file please consult the JDK logging documentation.

Vert.x also provides a slightly more convenient way to specify a configuration file without having to set a system property.
Just provide a JUL config file with the name `vertx-default-jul-logging.properties` on your classpath (e.g. inside your fatjar) and Vert.x will use that to configure JUL.

[[netty-logging]]
=== Netty logging

Netty does not rely on external logging configuration (e.g system properties).
Instead, it implements a logging configuration based on the logging libraries visible from the Netty classes:

* use `SLF4J` library if it is visible
* otherwise use `Log4j` if it is visible
* otherwise use `Log4j2` if it is visible
* otherwise fallback to `java.util.logging`

NOTE: The eagle eyes among you might have noticed that Vert.x follows the same order of preference.

The logger implementation can be forced to a specific implementation by setting Netty's internal logger implementation directly on `io.netty.util.internal.logging.InternalLoggerFactory`:

[source,java]
----
// Force logging to Log4j 2
InternalLoggerFactory.setDefaultFactory(Log4J2LoggerFactory.INSTANCE);
----

=== Troubleshooting

==== SLF4J warning at startup

If, when you start your application, you see the following message:

----
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
----

It means that you have SLF4J-API in your classpath but no actual binding. Messages logged with SLF4J will be dropped.
You should add a binding to your classpath. Check https://www.slf4j.org/manual.html#swapping to pick a binding and configure it.

Be aware that Netty looks for the SLF4-API jar and uses it by default.

==== Connection reset by peer

If your logs show a bunch of:

----
io.vertx.core.net.impl.ConnectionBase
SEVERE: java.io.IOException: Connection reset by peer
----

It means that the client is resetting the HTTP connection instead of closing it. This message also indicates that you
may have not consumed the complete payload (the connection was cut before you were able to).

== Host name resolution

Vert.x uses an an address resolver for resolving host name into IP addresses instead of
the JVM built-in blocking resolver.

A host name resolves to an IP address using:

- the _hosts_ file of the operating system
- otherwise DNS queries against a list of servers

By default it will use the list of the system DNS server addresses from the environment, if that list cannot be
retrieved it will use Google's public DNS servers `"8.8.8.8"` and `"8.8.4.4"`.

DNS servers can be also configured when creating a `link:../../apidocs/io/vertx/core/Vertx.html[Vertx]` instance:

[source,java]
----
Vertx vertx = Vertx.vertx(new VertxOptions().
    setAddressResolverOptions(
        new AddressResolverOptions().
            addServer("192.168.0.1").
            addServer("192.168.0.2:40000"))
);
----

The default port of a DNS server is `53`, when a server uses a different port, this port can be set
using a colon delimiter: `192.168.0.2:40000`.

NOTE: sometimes it can be desirable to use the JVM built-in resolver, the JVM system property
_-Dvertx.disableDnsResolver=true_ activates this behavior

=== Failover

When a server does not reply in a timely manner, the resolver will try the next one from the list, the search
is limited by `link:../../apidocs/io/vertx/core/dns/AddressResolverOptions.html#setMaxQueries-int-[setMaxQueries]` (the default value is `4` queries).

A DNS query is considered as failed when the resolver has not received a correct answer within
`link:../../apidocs/io/vertx/core/dns/AddressResolverOptions.html#getQueryTimeout--[getQueryTimeout]` milliseconds (the default value is `5` seconds).

=== Server list rotation

By default the dns server selection uses the first one, the remaining servers are used for failover.

You can configure `link:../../apidocs/io/vertx/core/dns/AddressResolverOptions.html#setRotateServers-boolean-[setRotateServers]` to `true` to let
the resolver perform a round-robin selection instead. It spreads the query load among the servers and avoids
all lookup to hit the first server of the list.

Failover still applies and will use the next server in the list.

=== Hosts mapping

The _hosts_ file of the operating system is used to perform a hostname lookup for an ipaddress.

An alternative _hosts_ file can be used instead:

[source,java]
----
Vertx vertx = Vertx.vertx(new VertxOptions().
    setAddressResolverOptions(
        new AddressResolverOptions().
            setHostsPath("/path/to/hosts"))
);
----

=== Search domains

By default the resolver will use the system DNS search domains from the environment. Alternatively an explicit search domain
list can be provided:

[source,java]
----
Vertx vertx = Vertx.vertx(new VertxOptions().
    setAddressResolverOptions(
        new AddressResolverOptions().addSearchDomain("foo.com").addSearchDomain("bar.com"))
);
----

When a search domain list is used, the threshold for the number of dots is `1` or loaded from `/etc/resolv.conf`
on Linux, it can be configured to a specific value with `link:../../apidocs/io/vertx/core/dns/AddressResolverOptions.html#setNdots-int-[setNdots]`.

=== MacOS configuration

MacOS has a specific native extension to get the name server configuration of the system based on https://opensource.apple.com/tarballs/mDNSResponder/[Apple's open source mDNSResponder]. When this extension is not present,
Netty logs the following warning.

----
[main] WARN io.netty.resolver.dns.DnsServerAddressStreamProviders - Can not find io.netty.resolver.dns.macos.MacOSDnsServerAddressStreamProvider in the classpath, fallback to system defaults. This may result in incorrect DNS resolutions on MacOS.
----

This extension is not required as its absence does not prevent Vert.x to execute, yet is *recommended*.

You can add it to your classpath to improve the integration and remove the warning.

.Intel-based Mac
[source,xml]
----
<profile>
  <id>mac-intel</id>
  <activation>
    <os>
      <family>mac</family>
      <arch>x86_64</arch>
    </os>
  </activation>
  <dependencies>
    <dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-resolver-dns-native-macos</artifactId>
      <classifier>osx-x86_64</classifier>
      <!--<version>Should align with netty version that Vert.x uses</version>-->
    </dependency>
  </dependencies>
</profile>
----

.M1/M2 Mac
[source,xml]
----
<profile>
  <id>mac-silicon</id>
  <activation>
    <os>
      <family>mac</family>
      <arch>aarch64</arch>
    </os>
  </activation>
  <dependencies>
    <dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-resolver-dns-native-macos</artifactId>
      <classifier>osx-aarch_64</classifier>
      <!--<version>Should align with netty version that Vert.x uses</version>-->
    </dependency>
  </dependencies>
</profile>
----

[#_native_transports]
== Native transports

Vert.x can run with http://netty.io/wiki/native-transports.html[native transports] (when available) on BSD (OSX) and Linux:

[source,java]
----
Vertx vertx = Vertx.vertx(new VertxOptions().
  setPreferNativeTransport(true)
);

// True when native is available
boolean usingNative = vertx.isNativeTransportEnabled();
System.out.println("Running with native: " + usingNative);
----

NOTE: Preferring native transport will not prevent the application to execute (for example a native dependency might be missing).If your application requires native transport, you need to check `link:../../apidocs/io/vertx/core/Vertx.html#isNativeTransportEnabled--[isNativeTransportEnabled]`.

You can also explicitly configure the transport to use:

[source,java]
----
Transport transport = Transport.nativeTransport();

// Or use a very specific transport
transport = Transport.EPOLL;

Vertx vertx = Vertx.builder()
  .withTransport(transport)
  .build();
----

=== Native epoll

Native on Linux gives you extra networking options:

* `SO_REUSEPORT`
* `TCP_QUICKACK`
* `TCP_CORK`
* `TCP_FASTOPEN`
* `TCP_USER_TIMEOUT`

You need to add the following dependency in your classpath:

[source,xml]
----
<dependency>
  <groupId>io.netty</groupId>
  <artifactId>netty-transport-native-epoll</artifactId>
  <classifier>linux-x86_64</classifier>
  <!--<version>Should align with netty version that Vert.x uses</version>-->
</dependency>
----

=== Native io_uring

You need to add the following dependency in your classpath:

[source,xml]
----
<dependency>
  <groupId>io.netty</groupId>
  <classifier>linux-x86_64</classifier>
  <artifactId>netty-transport-native-io_uring</artifactId>
  <!--<version>Should align with netty version that Vert.x uses</version>-->
</dependency>
----

=== Native kqueue

You need to add the following dependency in your classpath:

.Intel-based Mac
[source,xml]
----
<dependency>
  <groupId>io.netty</groupId>
  <artifactId>netty-transport-native-kqueue</artifactId>
  <classifier>osx-x86_64</classifier>
  <!--<version>Should align with netty version that Vert.x uses</version>-->
</dependency>
----

.M1/M2 Mac
[source,xml]
----
<dependency>
<groupId>io.netty</groupId>
<artifactId>netty-transport-native-kqueue</artifactId>
<classifier>osx-aarch_64</classifier>
<!--<version>Should align with netty version that Vert.x uses</version>-->
</dependency>
----

MacOS Sierra and above are supported.

Native on BSD gives you extra networking options:

* `SO_REUSEPORT`

[source,java]
----
vertx.createHttpServer(new HttpServerOptions().setReusePort(reusePort));
----

== Security notes

Vert.x is a toolkit, not an opinionated framework where we force you to do things in a certain way. This gives you
great power as a developer but with that comes great responsibility.

As with any toolkit, it's possible to write insecure applications, so you should always be careful when developing
your application especially if it's exposed to the public (e.g. over the internet).

=== Web applications

If writing a web application it's highly recommended that you use Vert.x-Web instead of Vert.x core directly for
serving resources and handling file uploads.

Vert.x-Web normalises the path in requests to prevent malicious clients from crafting URLs to access resources
outside of the web root.

Similarly for file uploads Vert.x-Web provides functionality for uploading to a known place on disk and does not rely
on the filename provided by the client in the upload which could be crafted to upload to a different place on disk.

Vert.x core itself does not provide such checks so it would be up to you as a developer to implement them yourself.

=== Clustered event bus traffic

When clustering the event bus between different Vert.x nodes on a network, the traffic is sent un-encrypted across the
wire, so do not use this if you have confidential data to send and your Vert.x nodes are not on a trusted network.

=== Standard security best practices

Any service can have potentially vulnerabilities whether it's written using Vert.x or any other toolkit so always
follow security best practice, especially if your service is public facing.

For example you should always run them in a DMZ and with an user account that has limited rights in order to limit
the extent of damage in case the service was compromised.

== Configuring Vert.x cache

When Vert.x needs to read a file from the classpath (embedded in a fat jar, in a jar form the classpath or a file
that is on the classpath), it copies it to a cache directory. The reason behind this is simple: reading a file
from a jar or from an input stream is blocking. So to avoid to pay the price every time, Vert.x copies the file to
its cache directory and reads it from there every subsequent read. This behavior can be configured.

First, by default, Vert.x uses `$CWD/.vertx` as cache directory. It creates a unique directory inside this one to
avoid conflicts. This location can be configured by using the `vertx.cacheDirBase` system property. For instance
if the current working directory is not writable (such as in an immutable container context), launch your
application with:

[source]
----
java -jar my-fat.jar vertx.cacheDirBase=/tmp/vertx-cache
----

IMPORTANT: the directory must be **writable**.

When you are editing resources such as HTML, CSS or JavaScript, this cache mechanism can be annoying as it serves
only the first version of the file (and so you won't see your edits if you reload your page). To avoid this
behavior, launch your application with `-Dvertx.disableFileCaching=true`. With this setting, Vert.x still uses
the cache, but always refresh the version stored in the cache with the original source. So if you edit a file
served from the classpath and refresh your browser, Vert.x reads it from the classpath, copies it to the cache
directory and serves it from there. Do not use this setting in production, it can kill your performances.

Finally, you can disable completely the cache by using `-Dvertx.disableFileCPResolving=true`. This setting is not
without consequences. Vert.x would be unable to read any files from the classpath (only from the file system). Be
very careful when using this setting.