Doc fixes and stop exporting ReplyChecked and ReplyUnchecked

This commit is contained in:
Andrew Gallant (Ocelot) 2012-06-05 00:15:14 -04:00 committed by Přemysl Janouch
parent a9eae45cb3
commit 08275ebda8
Signed by: p
GPG Key ID: A0420B94F92B9493
2 changed files with 36 additions and 13 deletions

View File

@ -22,8 +22,9 @@ type Cookie struct {
// function for more info on those.) // function for more info on those.)
// Note that a sequence number is not set until just before the request // Note that a sequence number is not set until just before the request
// corresponding to this cookie is sent over the wire. // corresponding to this cookie is sent over the wire.
// This function should not be used. It is exported for use in the extension //
// sub-packages. // Unless you're building requests from bytes by hand, this method should
// not be used.
func (c *Conn) NewCookie(checked, reply bool) *Cookie { func (c *Conn) NewCookie(checked, reply bool) *Cookie {
cookie := &Cookie{ cookie := &Cookie{
conn: c, conn: c,
@ -64,21 +65,25 @@ func (c *Conn) NewCookie(checked, reply bool) *Cookie {
// Reply detects whether this is a checked or unchecked cookie, and calls // Reply detects whether this is a checked or unchecked cookie, and calls
// 'replyChecked' or 'replyUnchecked' appropriately. // 'replyChecked' or 'replyUnchecked' appropriately.
// This should not be used. It is exported for use in extension sub-packages. //
// Unless you're building requests from bytes by hand, this method should
// not be used.
func (c Cookie) Reply() ([]byte, error) { func (c Cookie) Reply() ([]byte, error) {
// checked // checked
if c.errorChan != nil { if c.errorChan != nil {
return c.ReplyChecked() return c.replyChecked()
} }
return c.ReplyUnchecked() return c.replyUnchecked()
} }
// ReplyChecked waits for a response on either the replyChan or errorChan // replyChecked waits for a response on either the replyChan or errorChan
// channels. If the former arrives, the bytes are returned with a nil error. // channels. If the former arrives, the bytes are returned with a nil error.
// If the latter arrives, no bytes are returned (nil) and the error received // If the latter arrives, no bytes are returned (nil) and the error received
// is returned. // is returned.
// This should not be used. It is exported for use in extension sub-packages. //
func (c Cookie) ReplyChecked() ([]byte, error) { // Unless you're building requests from bytes by hand, this method should
// not be used.
func (c Cookie) replyChecked() ([]byte, error) {
if c.replyChan == nil { if c.replyChan == nil {
return nil, errors.New("Cannot call 'replyChecked' on a cookie that " + return nil, errors.New("Cannot call 'replyChecked' on a cookie that " +
"is not expecting a *reply* or an error.") "is not expecting a *reply* or an error.")
@ -97,14 +102,16 @@ func (c Cookie) ReplyChecked() ([]byte, error) {
panic("unreachable") panic("unreachable")
} }
// ReplyChecked waits for a response on either the replyChan or pingChan // replyUnchecked waits for a response on either the replyChan or pingChan
// channels. If the former arrives, the bytes are returned with a nil error. // channels. If the former arrives, the bytes are returned with a nil error.
// If the latter arrives, no bytes are returned (nil) and a nil error // If the latter arrives, no bytes are returned (nil) and a nil error
// is returned. (In the latter case, the corresponding error can be retrieved // is returned. (In the latter case, the corresponding error can be retrieved
// from (Wait|Poll)ForEvent asynchronously.) // from (Wait|Poll)ForEvent asynchronously.)
// In all honesty, you *probably* don't want to use this method. // In all honesty, you *probably* don't want to use this method.
// This should not be used. It is exported for use in extension sub-packages. //
func (c Cookie) ReplyUnchecked() ([]byte, error) { // Unless you're building requests from bytes by hand, this method should
// not be used.
func (c Cookie) replyUnchecked() ([]byte, error) {
if c.replyChan == nil { if c.replyChan == nil {
return nil, errors.New("Cannot call 'replyUnchecked' on a cookie " + return nil, errors.New("Cannot call 'replyUnchecked' on a cookie " +
"that is not expecting a *reply*.") "that is not expecting a *reply*.")
@ -127,7 +134,9 @@ func (c Cookie) ReplyUnchecked() ([]byte, error) {
// Thus, pingChan is sent a value when the *next* reply is read. // Thus, pingChan is sent a value when the *next* reply is read.
// If no more replies are being processed, we force a round trip request with // If no more replies are being processed, we force a round trip request with
// GetInputFocus. // GetInputFocus.
// This should not be used. It is exported for use in extension sub-packages. //
// Unless you're building requests from bytes by hand, this method should
// not be used.
func (c Cookie) Check() error { func (c Cookie) Check() error {
if c.replyChan != nil { if c.replyChan != nil {
return errors.New("Cannot call 'Check' on a cookie that is " + return errors.New("Cannot call 'Check' on a cookie that is " +

View File

@ -162,7 +162,7 @@ var NewExtErrorFuncs = make(map[string]map[int]NewErrorFun)
// error. // error.
type eventOrError interface{} type eventOrError interface{}
// NewID generates a new unused ID for use with requests like CreateWindow. // NewId generates a new unused ID for use with requests like CreateWindow.
// If no new ids can be generated, the id returned is 0 and error is non-nil. // If no new ids can be generated, the id returned is 0 and error is non-nil.
// This shouldn't be used directly, and is exported for use in the extension // This shouldn't be used directly, and is exported for use in the extension
// sub-packages. // sub-packages.
@ -269,6 +269,20 @@ type request struct {
// a request type, and sends it over the Conn.reqChan channel. // a request type, and sends it over the Conn.reqChan channel.
// Note that the sequence number is added to the cookie after it is sent // Note that the sequence number is added to the cookie after it is sent
// over the request channel, but before it is sent to X. // over the request channel, but before it is sent to X.
//
// Note that you may safely use NewRequest to send arbitrary byte requests
// to X. The resulting cookie can be used just like any normal cookie and
// abides by the same rules, except that for replies, you'll get back the
// raw byte data. This may be useful for performance critical sections where
// every allocation counts, since all X requests in XGB allocate a new byte
// slice. In contrast, NewRequest allocates one small request struct and
// nothing else. (Except when the cookie buffer is full and has to be flushed.)
//
// If you're using NewRequest manually, you'll need to use NewCookie to create
// a new cookie.
//
// In all likelihood, you should be able to copy and paste with some minor
// edits the generated code for the request you want to issue.
func (c *Conn) NewRequest(buf []byte, cookie *Cookie) { func (c *Conn) NewRequest(buf []byte, cookie *Cookie) {
c.reqChan <- &request{buf: buf, cookie: cookie} c.reqChan <- &request{buf: buf, cookie: cookie}
} }