clang-tools 8.0.0

Transport.h
Go to the documentation of this file.
1 //===--- Transport.h - sending and receiving LSP messages -------*- C++ -*-===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 // The language server protocol is usually implemented by writing messages as
11 // JSON-RPC over the stdin/stdout of a subprocess. However other communications
12 // mechanisms are possible, such as XPC on mac.
13 //
14 // The Transport interface allows the mechanism to be replaced, and the JSONRPC
15 // Transport is the standard implementation.
16 //
17 //===----------------------------------------------------------------------===//
18
19 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_TRANSPORT_H_
20 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_TRANSPORT_H_
21
22 #include "llvm/ADT/StringRef.h"
23 #include "llvm/Support/JSON.h"
24 #include "llvm/Support/raw_ostream.h"
25
26 namespace clang {
27 namespace clangd {
28
29 // A transport is responsible for maintaining the connection to a client
30 // application, and reading/writing structured messages to it.
31 //
32 // Transports have limited thread safety requirements:
33 // - messages will not be sent concurrently
34 // - messages MAY be sent while loop() is reading, or its callback is active
35 class Transport {
36 public:
37 virtual ~Transport() = default;
38
39 // Called by Clangd to send messages to the client.
40 virtual void notify(llvm::StringRef Method, llvm::json::Value Params) = 0;
41 virtual void call(llvm::StringRef Method, llvm::json::Value Params,
42 llvm::json::Value ID) = 0;
43 virtual void reply(llvm::json::Value ID,
44 llvm::Expected<llvm::json::Value> Result) = 0;
45
46 // Implemented by Clangd to handle incoming messages. (See loop() below).
47 class MessageHandler {
48 public:
49 virtual ~MessageHandler() = default;
50 // Handler returns true to keep processing messages, or false to shut down.
51 virtual bool onNotify(llvm::StringRef Method, llvm::json::Value) = 0;
52 virtual bool onCall(llvm::StringRef Method, llvm::json::Value Params,
53 llvm::json::Value ID) = 0;
54 virtual bool onReply(llvm::json::Value ID,
55 llvm::Expected<llvm::json::Value> Result) = 0;
56 };
57 // Called by Clangd to receive messages from the client.
58 // The transport should in turn invoke the handler to process messages.
59 // If handler returns false, the transport should immedately exit the loop.
60 // (This is used to implement the `exit` notification).
61 // Otherwise, it returns an error when the transport becomes unusable.
62 virtual llvm::Error loop(MessageHandler &) = 0;
63 };
64
65 // Controls the way JSON-RPC messages are encoded (both input and output).
66 enum JSONStreamStyle {
67 // Encoding per the LSP specification, with mandatory Content-Length header.
68 Standard,
69 // Messages are delimited by a '---' line. Comment lines start with #.
70 Delimited
71 };
72
73 // Returns a Transport that speaks JSON-RPC over a pair of streams.
74 // The input stream must be opened in binary mode.
75 // If InMirror is set, data read will be echoed to it.
76 //
77 // The use of C-style std::FILE* input deserves some explanation.
78 // Previously, std::istream was used. When a debugger attached on MacOS, the
79 // process received EINTR, the stream went bad, and clangd exited.
80 // A retry-on-EINTR loop around reads solved this problem, but caused clangd to
81 // sometimes hang rather than exit on other OSes. The interaction between
82 // istreams and signals isn't well-specified, so it's hard to get this right.
83 // The C APIs seem to be clearer in this respect.
84 std::unique_ptr<Transport>
85 newJSONTransport(std::FILE *In, llvm::raw_ostream &Out,
86 llvm::raw_ostream *InMirror, bool Pretty,
87 JSONStreamStyle = JSONStreamStyle::Standard);
88
89 #ifdef CLANGD_BUILD_XPC
90 // Returns a Transport for macOS based on XPC.
91 // Clangd with this transport is meant to be run as bundled XPC service.
92 std::unique_ptr<Transport> newXPCTransport();
93 #endif
94
95 } // namespace clangd
96 } // namespace clang
97
98 #endif
clang::clangd::JSONStreamStyle
JSONStreamStyle
Definition: Transport.h:66
clang::clangd::Transport::MessageHandler::~MessageHandler
virtual ~MessageHandler()=default
clang::clangd::Transport
Definition: Transport.h:35
clang::clangd::newXPCTransport
std::unique_ptr< Transport > newXPCTransport()
Definition: XPCTransport.cpp:212
clang::clangd::Transport::MessageHandler
Definition: Transport.h:47
clang::clangd::Transport::MessageHandler::onNotify
virtual bool onNotify(llvm::StringRef Method, llvm::json::Value)=0
clang::clangd::newJSONTransport
std::unique_ptr< Transport > newJSONTransport(std::FILE *In, llvm::raw_ostream &Out, llvm::raw_ostream *InMirror, bool Pretty, JSONStreamStyle Style)
Definition: JSONTransport.cpp:293
clang::clangd::Transport::notify
virtual void notify(llvm::StringRef Method, llvm::json::Value Params)=0
Result
llvm::Optional< llvm::Expected< tooling::AtomicChanges > > Result
Definition: ClangdServer.cpp:60
clang::clangd::Delimited
Definition: Transport.h:70
clang::clangd::Transport::~Transport
virtual ~Transport()=default
clang::clangd::CompletionItemKind::Method
clang::clangd::Transport::loop
virtual llvm::Error loop(MessageHandler &)=0
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ChangeNamespace.cpp:18
clang::clangd::Transport::reply
virtual void reply(llvm::json::Value ID, llvm::Expected< llvm::json::Value > Result)=0
clang::clangd::Standard
Definition: Transport.h:68
clang::clangd::Transport::call
virtual void call(llvm::StringRef Method, llvm::json::Value Params, llvm::json::Value ID)=0
clang::clangd::Transport::MessageHandler::onCall
virtual bool onCall(llvm::StringRef Method, llvm::json::Value Params, llvm::json::Value ID)=0
clang::clangd::Transport::MessageHandler::onReply
virtual bool onReply(llvm::json::Value ID, llvm::Expected< llvm::json::Value > Result)=0