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