/*@jsxRuntime automatic @jsxImportSource react*/
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = Object.assign({
    p: "p",
    a: "a",
    h2: "h2",
    img: "img",
    h3: "h3",
    pre: "pre",
    code: "code",
    span: "span"
  }, props.components), {Alert, Link} = _components;
  if (!Alert) _missingMdxReference("Alert", true);
  if (!Link) _missingMdxReference("Link", true);
  return _jsxs(_Fragment, {
    children: [_jsx(_components.p, {
      children: "Under the hood, the vert.x Con­text class plays a crit­i­cal part in main­tain­ing the thread-​safety guar­an­tees of ver­ti­cles. Most of the time, vert.x coders don’t need to make use of Con­text ob­jects di­rectly. How­ever, some­times you may need to. This ar­ti­cle pro­vides a brief in­tro­duc­tion to the vert.x Con­text class, which cov­ers why it’s im­por­tant, and why and when you might wish to make use of the Con­text di­rectly, based on the au­thor’s ex­pe­ri­ence of build­ing a generic async li­brary which can be used with vert.x."
    }), "\n", _jsx(Alert, {
      info: true,
      children: _jsxs(_components.p, {
        children: ["This is a re-​publication of the fol­low­ing ", _jsx(_components.a, {
          href: "http://www.millross-consultants.com/vertx_context_object.html",
          children: "blog post"
        })]
      })
    }), "\n", _jsxs(_components.h2, {
      id: "introduction",
      children: [_jsx(_components.a, {
        "aria-hidden": true,
        tabIndex: "-1",
        className: "heading-anchor",
        href: "#introduction"
      }), "Introduction"]
    }), "\n", _jsxs(_components.p, {
      children: ["Re­cently I’ve been look­ing at the pos­si­bil­ity of build­ing an asyn­chro­nous ver­sion of the ", _jsx(_components.a, {
        href: "http://www.pac4j.org",
        children: "pac4j"
      }), " li­brary, with a view to then mi­grat­ing the ", _jsx(_components.a, {
        href: "https://github.com/pac4j/vertx-pac4j",
        children: "vertx-​pac4j"
      }), " im­ple­men­ta­tion to use the asyn­chro­nous ver­sion of pac4j by de­fault."]
    }), "\n", _jsxs(_components.p, {
      children: ["I’m keen (for ob­vi­ous rea­sons) that the async ver­sion of pac4j is not tightly cou­pled to  one par­tic­u­lar asyn­chro­nous/non-​blocking frame­work, I de­cided to ex­pose the API via the ", _jsx(_components.a, {
        href: "http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html",
        children: "Com­pletable­Fu­ture"
      }), " class, using this to wrap val­ues which will be de­ter­mined in the fu­ture. How­ever, I opted to use the ", _jsx(Link, {
        href: "/",
        passHref: true,
        children: _jsx(_components.a, {
          href: "",
          children: "vert.x"
        })
      }), " frame­work for my asyn­chro­nous test­ing as a way of test­ing the API as it emerged. This in turn has led me to learn some as­pects of the vert.x ", _jsx(Link, {
        href: "/docs/apidocs/io/vertx/core/Context.html",
        passHref: true,
        children: _jsx(_components.a, {
          href: "",
          children: "Con­text"
        })
      }), " class which I didn’t re­ally un­der­stand be­fore."]
    }), "\n", _jsx(Alert, {
      info: true,
      children: _jsx(_components.p, {
        children: "The in­for­ma­tion pre­sented re­lates to Vert.x ver­sion 3.3.3. It is con­ceiv­able that later ver­sions of vert.x could ren­der as­pects of this ar­ti­cle in­cor­rect."
      })
    }), "\n", _jsxs(_components.h2, {
      id: "introduction-to-the-context-class",
      children: [_jsx(_components.a, {
        "aria-hidden": true,
        tabIndex: "-1",
        className: "heading-anchor",
        href: "#introduction-to-the-context-class"
      }), "Introduction to the Context class"]
    }), "\n", _jsxs(_components.p, {
      children: ["When­ever a vert.x ", _jsx(Link, {
        href: "/docs/apidocs/io/vertx/core/Handler.html",
        passHref: true,
        children: _jsx(_components.a, {
          href: "",
          children: "Han­dler"
        })
      }), " is ex­e­cuted, or the start or step method of a ver­ti­cle is called, then that ex­e­cu­tion is as­so­ci­ated with a spe­cific con­text. Gen­er­ally a con­text is an event-​loop con­text and is there­fore as­so­ci­ated with an event loop thread (ex­cep­tions are cov­ered in the Fur­ther Read­ing ref­er­enced below). Con­texts are prop­a­gated. When a han­dler is set by code run­ning on a spe­cific con­text, then that han­dler will also be ex­e­cuted on the same con­text. This means for ex­am­ple, that if the start method of a ver­ti­cle in­stance sets a num­ber of event bus han­dlers (as many do), then they will all run on the same con­text as the start method for that ver­ti­cle (so all han­dlers for that ver­ti­cle in­stance will share a com­mon con­text)."]
    }), "\n", _jsx(_components.p, {
      children: "A schematic of the re­la­tion­ships be­tween non-​worker ver­ti­cles, con­texts and event­loop threads is shown in Fig­ure 1."
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.img, {
        src: "/images/blog/vertx3-intro-to-context-object/VertxContextRelationships.png",
        alt: "Vertx Context/Thread/Verticle Relationships"
      })
    }), "\n", _jsx(_components.p, {
      children: "Note that each ver­ti­cle ef­fec­tively has only one con­text for han­dlers cre­ated by its start method, and each con­text is bound to a sin­gle event-​loop thread. A given event-​loop thread can, how­ever, have mul­ti­ple con­texts bound to it."
    }), "\n", _jsxs(_components.h2, {
      id: "when-are-contexts-not-propagated",
      children: [_jsx(_components.a, {
        "aria-hidden": true,
        tabIndex: "-1",
        className: "heading-anchor",
        href: "#when-are-contexts-not-propagated"
      }), "When are contexts not propagated?"]
    }), "\n", _jsx(_components.p, {
      children: "When a ver­ti­cle’s start method is called, a new con­text is cre­ated. If 4 iden­ti­cal ver­ti­cles are de­ployed via the in­stances pa­ra­me­ter on De­ploy­men­tOp­tions, the start method of each will be on a new con­text. This is log­i­cal as we may not want all non-​worker ver­ti­cles to be bound to a sin­gle event­loop thread when mul­ti­ple event­loop threads are avail­able."
    }), "\n", _jsxs(_components.h2, {
      id: "threading-guarantees",
      children: [_jsx(_components.a, {
        "aria-hidden": true,
        tabIndex: "-1",
        className: "heading-anchor",
        href: "#threading-guarantees"
      }), "Threading Guarantees"]
    }), "\n", _jsx(_components.p, {
      children: "There are cer­tain con­se­quences of the prop­a­ga­tion of con­texts to han­dlers as men­tioned above. The most im­por­tant one is that since all han­dlers in a given event­loop ver­ti­cle run on the same con­text (the one on which its start method ran), they all run on the same event­loop thread. This gives rise to the thread­ing guar­an­tee within vert.x, that as long as a given ver­ti­cle is the only one to ever ac­cess a piece of state, then that state is being ac­cessed by only one thread, so no syn­chro­niza­tion will be nec­es­sary."
    }), "\n", _jsxs(_components.h2, {
      id: "exception-handling",
      children: [_jsx(_components.a, {
        "aria-hidden": true,
        tabIndex: "-1",
        className: "heading-anchor",
        href: "#exception-handling"
      }), "Exception Handling"]
    }), "\n", _jsx(_components.p, {
      children: "Each con­text can have its own ex­cep­tion han­dler at­tached for han­dling ex­cep­tions which occur dur­ing event loop pro­cess­ing."
    }), "\n", _jsxs(_components.h3, {
      id: "why-might-you-not-want-the-default-exception-handler",
      children: [_jsx(_components.a, {
        "aria-hidden": true,
        tabIndex: "-1",
        className: "heading-anchor",
        href: "#why-might-you-not-want-the-default-exception-handler"
      }), "Why might you not want the default exception handler?"]
    }), "\n", _jsx(_components.p, {
      children: "As one ex­am­ple, you might have some ver­ti­cles run­ning whose job it is to mon­i­tor other ver­ti­cles, and if some­thing ap­pears to go wrong with them, un­de­ploy and restart them, a fre­quent pat­tern in an actor-​ or microservices-​ style archic­tec­ture. So one op­tion could be that when a su­per­vised ver­ti­cle en­coun­ters an un­re­cov­er­able error, it could sim­ply no­tify its su­per­vi­sor that it has gone wrong via an event­bus mes­sage, and its su­per­vi­sor could then un­de­ploy and re­de­ploy (and after a num­ber of fail­ures in rapid suc­ces­sion pos­si­bly give up hope or es­ca­late to its own su­per­vi­sor."
    }), "\n", _jsxs(_components.h2, {
      id: "going-off-context-and-getting-back-onto-a-particular-context",
      children: [_jsx(_components.a, {
        "aria-hidden": true,
        tabIndex: "-1",
        className: "heading-anchor",
        href: "#going-off-context-and-getting-back-onto-a-particular-context"
      }), "Going off-context and getting back onto a particular context"]
    }), "\n", _jsx(_components.p, {
      children: "There are sev­eral rea­sons why you might ex­e­cute code off-​context and then want to op­er­ate back on a vert.x con­text when com­plete. I’ll out­line a cou­ple of sce­nar­ios below"
    }), "\n", _jsxs(_components.h3, {
      id: "running-code-on-a-separate-thread",
      children: [_jsx(_components.a, {
        "aria-hidden": true,
        tabIndex: "-1",
        className: "heading-anchor",
        href: "#running-code-on-a-separate-thread"
      }), "Running code on a separate thread"]
    }), "\n", _jsx(_components.p, {
      children: "Firstly you might be using an asyn­chro­nous dri­ver which is en­tirely vertx-​unaware. Its code will run on non-​eventloop threads but it’s pos­si­ble you may then want to use the re­sults of that code to up­date in­for­ma­tion within your ver­ti­cle. If you don’t get back onto the cor­rect con­text, you can’t make any guar­an­tees about thread-​safety, so your sub­se­quent pro­cess­ing needs to be run back on the cor­rect event­loop thread."
    }), "\n", _jsxs(_components.h3, {
      id: "using-asynchronous-java-8-apis",
      children: [_jsx(_components.a, {
        "aria-hidden": true,
        tabIndex: "-1",
        className: "heading-anchor",
        href: "#using-asynchronous-java-8-apis"
      }), "Using asynchronous Java 8 APIs"]
    }), "\n", _jsx(_components.p, {
      children: "APIs such as Com­pletable­Fu­ture are context-​unaware. In one ex­am­ple, I cre­ated an al­ready com­pleted fu­ture on the vert.x event loop in a test. I then at­tached sub­se­quent pro­cess­ing to it via then run:"
    }), "\n", _jsx(_components.pre, {
      children: _jsxs(_components.code, {
        className: "hljs language-java",
        children: [_jsx(_components.span, {
          className: "hljs-meta",
          children: "@RunWith(VertxUnitRunner.class)"
        }), "\n", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "public"
        }), " ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "class"
        }), " ", _jsx(_components.span, {
          className: "hljs-title class_",
          children: "ImmediateCompletionTest"
        }), " {\n    ", _jsx(_components.span, {
          className: "hljs-meta",
          children: "@Rule"
        }), "\n    ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "public"
        }), " ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "final"
        }), " ", _jsx(_components.span, {
          className: "hljs-type",
          children: "RunTestOnContext"
        }), " ", _jsx(_components.span, {
          className: "hljs-variable",
          children: "rule"
        }), " ", _jsx(_components.span, {
          className: "hljs-operator",
          children: "="
        }), " ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "new"
        }), " ", _jsx(_components.span, {
          className: "hljs-title class_",
          children: "RunTestOnContext"
        }), "();\n\n    ", _jsx(_components.span, {
          className: "hljs-meta",
          children: "@Test"
        }), "\n    ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "public"
        }), " ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "void"
        }), " ", _jsx(_components.span, {
          className: "hljs-title function_",
          children: "testImmediateCompletion"
        }), _jsx(_components.span, {
          className: "hljs-params",
          children: "(TestContext context)"
        }), " {\n\n        ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "final"
        }), " ", _jsx(_components.span, {
          className: "hljs-type",
          children: "Async"
        }), " ", _jsx(_components.span, {
          className: "hljs-variable",
          children: "async"
        }), " ", _jsx(_components.span, {
          className: "hljs-operator",
          children: "="
        }), " context.async();\n        ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "final"
        }), " ", _jsx(_components.span, {
          className: "hljs-type",
          children: "Vertx"
        }), " ", _jsx(_components.span, {
          className: "hljs-variable",
          children: "vertx"
        }), " ", _jsx(_components.span, {
          className: "hljs-operator",
          children: "="
        }), " rule.vertx();\n        ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "final"
        }), " CompletableFuture<Integer> toComplete = ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "new"
        }), " ", _jsx(_components.span, {
          className: "hljs-title class_",
          children: "CompletableFuture"
        }), "<>();\n        ", _jsx(_components.span, {
          className: "hljs-comment",
          children: "// delay future completion by 500 ms"
        }), "\n        ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "final"
        }), " ", _jsx(_components.span, {
          className: "hljs-type",
          children: "String"
        }), " ", _jsx(_components.span, {
          className: "hljs-variable",
          children: "threadName"
        }), " ", _jsx(_components.span, {
          className: "hljs-operator",
          children: "="
        }), " Thread.currentThread().getName();\n        toComplete.complete(", _jsx(_components.span, {
          className: "hljs-number",
          children: "100"
        }), ");\n        toComplete.thenRun(() -> {\n            assertThat(Thread.currentThread().getName(), is(threadName));\n            async.complete();\n        });\n    }\n}\n"]
      })
    }), "\n", _jsx(_components.p, {
      children: "Naively one might ex­pect this to au­to­mat­i­cally run on the con­text, since it hasn’t left the event­loop thread on which the fu­ture was com­pleted, and in­deed it’s prov­able that it is on the cor­rect thread. How­ever, it will not be on the cor­rect con­text. This would mean that it wouldn’t, for ex­am­ple, in­voke any mod­i­fied ex­cep­tion han­dler at­tached to the con­text."
    }), "\n", _jsxs(_components.h3, {
      id: "getting-back-on-context",
      children: [_jsx(_components.a, {
        "aria-hidden": true,
        tabIndex: "-1",
        className: "heading-anchor",
        href: "#getting-back-on-context"
      }), "Getting back on context"]
    }), "\n", _jsx(_components.p, {
      children: "For­tu­nately, once we’ve left the con­text, it’s quite straight­for­ward to re­turn to it. Prior to de­f­i­n­i­tion of the code block within then­Run, we can use Vertx.cur­rent­Con­text() or vertx.getOr­Cre­ate­Con­text() to get a han­dle to the con­text on which our event­loop code is run­ning, We can then ex­e­cute the code block in­side a call to Con­text::runOn­Con­text, sim­i­lar to"
    }), "\n", _jsx(_components.pre, {
      children: _jsxs(_components.code, {
        className: "hljs language-java",
        children: [_jsx(_components.span, {
          className: "hljs-keyword",
          children: "final"
        }), " ", _jsx(_components.span, {
          className: "hljs-type",
          children: "Context"
        }), " ", _jsx(_components.span, {
          className: "hljs-variable",
          children: "currentContext"
        }), " ", _jsx(_components.span, {
          className: "hljs-operator",
          children: "="
        }), " vertx.getOrCreateContext();\ntoComplete.thenRun(() -> {\n        currentContext.runOnContext(v -> {\n        assertThat(Thread.currentThread().getName(), is(threadName));\n        async.complete();\n    }\n});\n"]
      })
    }), "\n", _jsx(_components.p, {
      children: "While get­ting back onto the cor­rect con­text may not be crit­i­cal if you have re­mained on the event loop thread through­out, it is crit­i­cal if you are going to in­voke sub­se­quent vert.x han­dlers, up­date ver­ti­cle state or any­thing sim­i­lar, so it’s a sen­si­ble gen­eral ap­proach."
    }), "\n", _jsxs(_components.h2, {
      id: "further-reading",
      children: [_jsx(_components.a, {
        "aria-hidden": true,
        tabIndex: "-1",
        className: "heading-anchor",
        href: "#further-reading"
      }), "Further Reading"]
    }), "\n", _jsxs(_components.p, {
      children: ["The vert.x team them­selves offer an ex­cel­lent blog about the Vert.x event­loop, with ex­cel­lent ma­te­r­ial on the con­text, on ", _jsx(_components.a, {
        href: "https://github.com/vietj/vertx-materials/blob/master/src/main/asciidoc/Demystifying_the_event_loop.adoc",
        children: "Github"
      }), "."]
    }), "\n", _jsxs(_components.h2, {
      id: "thanks",
      children: [_jsx(_components.a, {
        "aria-hidden": true,
        tabIndex: "-1",
        className: "heading-anchor",
        href: "#thanks"
      }), "Thanks"]
    }), "\n", _jsxs(_components.p, {
      children: ["Thanks very much to the vert.x core team for their clear github pages on the event­loop, and also to ", _jsx(_components.a, {
        href: "https://twitter.com/alexlehm?lang=en",
        children: "Alexan­der Lehmann"
      }), " for his an­swers to my stu­pid and naive ques­tions on the ", _jsx(_components.a, {
        href: "https://groups.google.com/forum/#!forum/vertx",
        children: "Vert.x google group"
      }), "."]
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, Object.assign({}, props, {
    children: _jsx(_createMdxContent, props)
  })) : _createMdxContent(props);
}
return {
  default: MDXContent
};
function _missingMdxReference(id, component) {
  throw new Error("Expected " + (component ? "component" : "object") + " `" + id + "` to be defined: you likely forgot to import, pass, or provide it.");
}


Blog

An Introduction to the Vert.x Context Object

Next post

Vert.x 3.4.0.Beta1 release

Previous post

Building services and APIs with AMQP 1.0

Blog

An Introduction to the Vert.x Context Object

Next post

Vert.x 3.4.0.Beta1 release

Previous post

Building services and APIs with AMQP 1.0

Related posts

Some Rest with Vert.x

My first Vert.x 3 Application

Real-time bidding with Websockets and Vert.x