3 * Copyright (c) 2007 - 2010, Blue Static <http://www.bluestatic.org>
5 * This program is free software; you can redistribute it and/or modify it under the terms of the GNU
6 * General Public License as published by the Free Software Foundation; either version 2 of the
7 * License, or (at your option) any later version.
9 * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
10 * even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 * General Public License for more details.
13 * You should have received a copy of the GNU General Public License along with this program; if not,
14 * write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
17 #import <Cocoa/Cocoa.h>
19 #import "Breakpoint.h"
20 #import "StackFrame.h"
22 @protocol DebuggerConnectionDelegate
;
24 // The DebuggerConnection is the communication layer between the application
25 // and the Xdebug engine. Clients can issue debugger commands using this class,
26 // which are sent in an asynchronous manner. Reads are also asynchronous and
27 // the primary client of this class should set itself as the delegate. The
28 // primary unit that this class deals with is the StackFrame; clients should
29 // maintain a stack structure and the Connection will inform the delegate when
30 // a new frame is created or the stack should be destroyed.
31 @interface DebuggerConnection
: NSObject
33 // The port to connect on.
36 // If the connection to the debugger engine is currently active.
39 // Human-readable status of the connection.
42 // The connection's delegate.
43 id
<DebuggerConnectionDelegate
> delegate
;
45 // The raw CFSocket on which the two streams are based. Strong.
48 // The read stream that is scheduled on the main run loop. Weak.
49 CFReadStreamRef readStream_
;
51 // The write stream. Weak.
52 CFWriteStreamRef writeStream_
;
54 // An ever-increasing integer that gives each transaction a unique ID for the
56 NSUInteger transactionID
;
58 // The most recently received transaction ID.
59 NSUInteger lastReadTransaction_
;
61 // The last transactionID written to the stream.
62 NSUInteger lastWrittenTransaction_
;
64 // Callback table. This maps transaction IDs to selectors. When the engine
65 // returns a response to the debugger, we will dispatch the response XML to
66 // the selector, based on transaction_id.
67 NSMutableDictionary
* callTable_
;
69 // To prevent blocked writing, we enqueue all writes and then wait for the
70 // write stream to tell us it's ready. We store the pending commands in this
71 // array. We use this as a stack (FIFO), with index 0 being first.
72 NSMutableArray
* queuedWrites_
;
74 // We send queued writes in multiple places, sometimes off a run loop event.
75 // Because of this, we need to ensure that only one client is dequeing and
77 NSRecursiveLock
* writeQueueLock_
;
79 // Information about the current read loop. We append to |currentPacket_|
80 // until |currentPacketSize_| has reached |packetSize_|.
81 NSMutableString
* currentPacket_
;
83 int currentPacketIndex_
;
85 // A dictionary that maps routingIDs to StackFrame objects.
86 NSMutableDictionary
* stackFrames_
;
87 // The stack depth for the current build of |stackFrames_|.
88 NSInteger stackDepth_
;
89 // The earliest transaction ID for the current build of |stackFrames_|.
90 NSInteger stackFirstTransactionID_
;
92 // This stores additional context information for the callback selector.
93 // This dictionary is keyed by the same transaction IDs in |callTable_|, but
94 // also stores some other object that can be accessed in the callback.
95 NSMutableDictionary
* callbackContext_
;
98 @
property (readonly
, copy
) NSString
* status
;
99 @
property (assign
) id
<DebuggerConnectionDelegate
> delegate
;
102 - (id
)initWithPort
:(NSUInteger
)aPort
;
106 - (NSString
*)remoteHost
;
108 - (NSArray
*)getCurrentStack
;
116 - (void)addBreakpoint
:(Breakpoint
*)bp
;
117 - (void)removeBreakpoint
:(Breakpoint
*)bp
;
120 - (NSArray
*)getProperty
:(NSString
*)property
;
124 // Delegate ////////////////////////////////////////////////////////////////////
126 @protocol DebuggerConnectionDelegate
<NSObject
>
128 // Passes up errors from SocketWrapper and any other errors generated by the
130 - (void)errorEncountered
:(NSString
*)error
;
132 // Called when the socket connects. Passed up from SocketWrapper.
133 - (void)debuggerConnected
;
135 // Called when we disconnect.
136 - (void)debuggerDisconnected
;
138 // Tells the debugger to destroy the current stack display.
139 - (void)clobberStack
;
141 // Tells the debugger that a new stack frame is avaliable.
142 - (void)newStackFrame
:(StackFrame
*)frame
;
144 // Tells the debugger that new source is available for the given frame.
145 - (void)sourceUpdated
:(StackFrame
*)frame
;