Skip to content

Commit

Permalink
udap: Added documentation for server and communicator
Browse files Browse the repository at this point in the history 
Signed-off-by: mstreeter10 <[email protected]>
  • Loading branch information
@mstreeter10
mstreeter10 committed Jan 3, 2024
1 parent b0ad7fb commit 8482f55
Show file tree
Hide file tree
Showing 2 changed files with 57 additions and 7 deletions.
34 changes: 31 additions & 3 deletions uni/ulsp/udap/communicator.icn
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ import json

class Communicator(udb, udbSock, filePath, progArgs, debuggerActive)

# Attempt to start udb if not already active and connect to it.
# Returns "success" if successful and an appropriate error string if otherwise.
method start_debugger(port)
local udbPath, dir, result

Expand All @@ -23,16 +25,20 @@ class Communicator(udb, udbSock, filePath, progArgs, debuggerActive)
return "success"
end

# Send a termination signal to udb.
method end_debugger()
kill(\udb, "SIGTERM")
debuggerActive := "n"
end

# Returns udb's absolute path.
method find_debugger()
return pathfind("udb")
end

method stackTrace()
# Returns a list of tables containing stack trace information.
# A table of with key "type" set to "crash" is returned if udb experiences an error.
method stack_trace()
local udbResTable, udbResTableList, i, frames

udbResTableList := list()
Expand All @@ -57,7 +63,9 @@ class Communicator(udb, udbSock, filePath, progArgs, debuggerActive)
return frames
end

method getScopes(frame)
# Returns a list of tables containing scope information.
# A table of with key "type" set to "crash" is returned if udb experiences an error.
method get_scopes(frame)
local udbResTableList, udbResTable, scopes, i, j, k, l, m

udbResTableList := list()
Expand Down Expand Up @@ -94,7 +102,9 @@ class Communicator(udb, udbSock, filePath, progArgs, debuggerActive)
return scopes
end

method getVariables(variablesReference)
# Returns a list of tables containing variable information.
# A table of with key "type" set to "crash" is returned if udb experiences an error.
method get_variables(variablesReference)
local udbResTable, udbResTableList, variables, cmd, i

udbResTableList := list()
Expand Down Expand Up @@ -129,6 +139,7 @@ class Communicator(udb, udbSock, filePath, progArgs, debuggerActive)
return variables
end

# Generator that suspends all udb commands needed for loading debuggee.
method load_cmds()
local dir

Expand All @@ -139,10 +150,13 @@ class Communicator(udb, udbSock, filePath, progArgs, debuggerActive)
else suspend "load " || filePath
end

# Sets the file path of the debuggee.
method set_filepath(fpath)
filePath := fpath
end

# Attempts to connect to udb on a specified port.
# Returns "success" if successful and an appropriate error string if otherwise.
method connect_udbsock(port)
if /port then return "udb communication port not declared"

Expand All @@ -160,11 +174,16 @@ class Communicator(udb, udbSock, filePath, progArgs, debuggerActive)
return "udap failed to connect to udb on port: " || port
end

# Disconnects from udb.
method disconnect_udbsock()
close(\udbSock)
udbSock := &null
end

# Attempts to read udb socket output.
# Returns what was read or fails if reading isn't possible.
# If 'wait' is not null, process will wait a maximum of 5 seconds for udb to respond.
# 'wait' should be not null if udap needs a response from udb.
method udb_output(wait)
local msg, i, seg, failsafe

Expand Down Expand Up @@ -198,6 +217,11 @@ class Communicator(udb, udbSock, filePath, progArgs, debuggerActive)
return msg
end

# Sends udb a command as 'exp' and returns what was output.
# A table of with key "type" set to "crash" is returned if udb experiences an error or if reading isn't possible.
# If 'wait' is not null, process will wait a maximum of 5 seconds for udb to respond.
# 'wait' should be not null if udap needs a response from udb.
# Will always return a crash table if a crash has happened unless if a call with 'resetError' not null has been executed.
method udb_input(exp, wait, resetError)
local udbRes, resultTable
static errorCalled
Expand Down Expand Up @@ -231,10 +255,14 @@ class Communicator(udb, udbSock, filePath, progArgs, debuggerActive)
}
end

# Returns the communcation source used to communicate with udb.
method get_communication_source()
if \udbSock then return udbSock
end

# Attempts to set breakpoints given DAP setBreakpoints request as 'arguments'.
# Gives a "verified" key to each breakpoint table and sets it based on if the breakpoint was successfully set or not.
# A table of with key "type" set to "crash" is returned if udb experiences an error.
method set_breakpoints(arguments)
local breakpoints, bp, line, cond, udbResTable, udbResTableList, i

Expand Down
30 changes: 26 additions & 4 deletions uni/ulsp/udap/server.icn
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ global seq, lastUdbCmd, waitingForTerminal, requestQueue

class Server(port, sock, communicator, shellProcessId, clientDetails, currentRequestBody, udbError)

# Main loop udap process.
method run()
local request_body, jsontable, request_seq, request_command, request_arguments, cmd

Expand All @@ -31,6 +32,7 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
}
end

# Given a DAP client request body, process that request.
method process_request(request_body)
local jsontable, request_seq, request_command, request_arguments, response_body

Expand Down Expand Up @@ -69,6 +71,7 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# Get Request #
#################################################################################

# Attempt to read messages from client given a socket and returns each message as a generator.
method get_request(sock)
local request_body, msg, len

Expand Down Expand Up @@ -106,6 +109,7 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# Build Response #
#################################################################################

# Create and return a response for client in json format.
method build_response(request_seq, success, request_command, body, message)
local responseTable, responseBody, responseHeader

Expand All @@ -132,6 +136,7 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# Build Request #
#################################################################################

# Create and return a request for client in json format.
method build_request(command, arguments)
local requestTable, requestBody, requestHeader

Expand All @@ -155,6 +160,7 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# Build Event #
#################################################################################

# Create and return an event for client in json format.
method build_event(event, body)
local eventTable, eventBody, eventHeader

Expand All @@ -178,6 +184,7 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# initialize #
########################################################

# Handles all the things required from a client "initialize" request.
method initialize(request_seq, request_command, request_arguments)
local capabilitiesTable, res, udbPort, startRes, event, req

Expand Down Expand Up @@ -211,6 +218,7 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# launch #
########################################################

# Handles all the things required from a client "launch" request.
method launch(request_seq, request_command, request_arguments)
local res, initEvent, pth, event, progPort

Expand Down Expand Up @@ -244,6 +252,7 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# set breakpoints #
########################################################

# Handles all the things required from a client "setBreakpoints" request.
method set_breakpoints(request_seq, request_command, request_arguments)
local res, breakpointTable, breakpoint, resTable

Expand All @@ -267,6 +276,7 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# threads #
########################################################

# Handles all the things required from a client "threads" request.
method threads(request_seq, request_command)
local res, threadsTable

Expand All @@ -281,10 +291,11 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# stackTrace #
########################################################

# Handles all the things required from a client "stackTrace" request.
method stackTrace(request_seq, request_command, request_arguments)
local res, stackList

stackList := communicator.stackTrace()
stackList := communicator.stack_trace()

if type(stackList) == "table" then {
if member(stackList, "type") then
Expand All @@ -301,10 +312,11 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# scopes #
########################################################

# Handles all the things required from a client "scopes" request.
method scopes(request_seq, request_command, request_arguments)
local res, scopes

scopes := communicator.getScopes(request_arguments["frameId"])
scopes := communicator.get_scopes(request_arguments["frameId"])

if type(scopes) == "table" then {
if member(scopes, "type") then
Expand All @@ -321,10 +333,11 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# variables #
########################################################

# Handles all the things required from a client "variables" request.
method variables(request_seq, request_command, request_arguments)
local res, variables

variables := communicator.getVariables(request_arguments["variablesReference"])
variables := communicator.get_variables(request_arguments["variablesReference"])

if type(variables) == "table" then {
if member(variables, "type") then
Expand All @@ -341,7 +354,7 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# acknowledge #
########################################################

# default response for request that only requires an acknowledgement
# Default response for request that only requires an acknowledgement.
method acknowledge(request_seq, request_command)
local res

Expand All @@ -353,6 +366,7 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# udb_listen #
########################################################

# Reads udb's communication socket and processes any output collected.
method udb_listen()
local outputTable, udbRes

Expand All @@ -368,6 +382,9 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# udb_input #
########################################################

# Sends udb a command as 'expression' and processes any output collected.
# If 'wait' is not null, process will wait a maximum of 5 seconds for udb to respond.
# 'wait' should be not null if udap needs a response from udb.
method udb_input(expression, wait)
local outputTable
every outputTable := communicator.udb_input(expression, wait) do {
Expand All @@ -379,6 +396,7 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# process_udb_output_table #
########################################################

# Given a udb output table as 'outputTable', process that table.
method process_udb_output_table(outputTable)
local udbRes := "", event

Expand Down Expand Up @@ -432,6 +450,7 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# evaluate #
########################################################

# Handles all the things required from a client "evaluate" request.
method evaluate(request_seq, request_command, request_arguments)
local res, expression, result := "", isEvalExp

Expand All @@ -456,6 +475,7 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# handle_error #
########################################################

# Handle a udb output table of "type" set to "crash".
method handle_error(outputTable)
local errorText, errorMessageTable, res, event

Expand Down Expand Up @@ -484,6 +504,7 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
# disconnect #
########################################################

# Disconnect from client and udb and startup as a fresh session.
method disconnect()
communicator.disconnect_udbsock()
communicator.udb_input(&null, &null, 1)
Expand All @@ -492,6 +513,7 @@ class Server(port, sock, communicator, shellProcessId, clientDetails, currentReq
startup()
end

# Attempt to open communication port for client and set default class parameters.
method startup()
every 1 to 5 do
if sock := open(port, "na") then {
Expand Down

0 comments on commit 8482f55

Please sign in to comment.