X-Git-Url: https://gerrit.fd.io/r/gitweb?a=blobdiff_plain;f=api%2Fapi.go;h=977b02ee1ba92e1b59997bdb06c34acaba756361;hb=e517439567ad843033257664fdfe90a9173b0aa6;hp=39fe60f0c32a42e2af1c75ddbf5291779d870d20;hpb=a3bb834db727a3ac9a1ffcfeae9265e5dead851f;p=govpp.git diff --git a/api/api.go b/api/api.go index 39fe60f..977b02e 100644 --- a/api/api.go +++ b/api/api.go @@ -1,76 +1,60 @@ -// Copyright (c) 2017 Cisco and/or its affiliates. +// Copyright (c) 2020 Cisco and/or its affiliates. // -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at: +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at: // -// http://www.apache.org/licenses/LICENSE-2.0 +// http://www.apache.org/licenses/LICENSE-2.0 // -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. package api import ( - "fmt" + "context" "time" ) -// MessageType represents the type of a VPP message. -// Note: this is currently derived from the message header (fields), -// and in many cases it does not represent the actual type of VPP message. -// This means that some replies can be identified as requests, etc. -// TODO: use services to identify type of message -type MessageType int - -const ( - // RequestMessage represents a VPP request message - RequestMessage MessageType = iota - // ReplyMessage represents a VPP reply message - ReplyMessage - // EventMessage represents a VPP event message - EventMessage - // OtherMessage represents other VPP message - OtherMessage -) - -// Message is an interface that is implemented by all VPP Binary API messages generated by the binapigenerator. -type Message interface { - // GetMessageName returns the original VPP name of the message, as defined in the VPP API. - GetMessageName() string - - // GetCrcString returns the string with CRC checksum of the message definition (the string represents a hexadecimal number). - GetCrcString() string - - // GetMessageType returns the type of the VPP message. - GetMessageType() MessageType -} - -// DataType is an interface that is implemented by all VPP Binary API data types by the binapi_generator. -type DataType interface { - // GetTypeName returns the original VPP name of the data type, as defined in the VPP API. - GetTypeName() string - - // GetCrcString returns the string with CRC checksum of the data type definition (the string represents a hexadecimal number). - GetCrcString() string -} - -// MessageDecoder provides functionality for decoding binary data to generated API messages. -type MessageDecoder interface { - // DecodeMsg decodes binary-encoded data of a message into provided Message structure. - DecodeMsg(data []byte, msg Message) error +// Connection represents the client connection to VPP API. +// +// NOTE: This API is EXPERIMENTAL. +type Connection interface { + // NewStream creates a new stream for sending and receiving messages. + // Context can be used to close the stream using cancel or timeout. + NewStream(ctx context.Context) (Stream, error) + + // Invoke can be used for a simple request-reply RPC. + // It creates stream and calls SendMsg with req and RecvMsg with reply. + Invoke(ctx context.Context, req Message, reply Message) error } -// MessageIdentifier provides identification of generated API messages. -type MessageIdentifier interface { - // GetMessageID returns message identifier of given API message. - GetMessageID(msg Message) (uint16, error) - - // LookupByID looks up message name and crc by ID - LookupByID(msgID uint16) (Message, error) +// Stream provides low-level access for sending and receiving messages. +// Users should handle correct type and ordering of messages. +// +// NOTE: This API is EXPERIMENTAL. +type Stream interface { + // SendMsg sends a message to the client. + // It blocks until message is sent to the transport. + // + // It is safe to have a goroutine calling SendMsg and another goroutine + // calling RecvMsg on the same stream at the same time, but it is not safe + // to call SendMsg on the same stream in different goroutines. + SendMsg(Message) error + + // RecvMsg blocks until a message is received or error occurs. + // + // It is safe to have a goroutine calling SendMsg and another goroutine + // calling RecvMsg on the same stream at the same time, but it is not safe + // to call SendMsg on the same stream in different goroutines. + RecvMsg() (Message, error) + + // Close closes the stream. Calling SendMsg and RecvMsg will return error + // after closing stream. + Close() error } // ChannelProvider provides the communication channel with govpp core. @@ -86,9 +70,6 @@ type ChannelProvider interface { // Channel provides methods for direct communication with VPP channel. type Channel interface { - // GetID returns channel's ID - GetID() uint16 - // SendRequest asynchronously sends a request to VPP. Returns a request context, that can be used to call ReceiveReply. // In case of any errors by sending, the error will be delivered to ReplyChan (and returned by ReceiveReply). SendRequest(msg Message) RequestCtx @@ -101,53 +82,44 @@ type Channel interface { // SubscribeNotification subscribes for receiving of the specified notification messages via provided Go channel. // Note that the caller is responsible for creating the Go channel with preferred buffer size. If the channel's // buffer is full, the notifications will not be delivered into it. - SubscribeNotification(notifChan chan Message, msgFactory func() Message) (*NotifSubscription, error) - - // UnsubscribeNotification unsubscribes from receiving the notifications tied to the provided notification subscription. - UnsubscribeNotification(subscription *NotifSubscription) error + SubscribeNotification(notifChan chan Message, event Message) (SubscriptionCtx, error) // SetReplyTimeout sets the timeout for replies from VPP. It represents the maximum time the API waits for a reply // from VPP before returning an error. SetReplyTimeout(timeout time.Duration) - // Close closes the API channel and releases all API channel-related resources in the ChannelProvider. + // CheckCompatibility checks the compatiblity for the given messages. + // It will return an error if any of the given messages are not compatible. + CheckCompatiblity(msgs ...Message) error + + // Close closes the API channel and releases all API channel-related resources + // in the ChannelProvider. Close() } -// RequestCtx is helper interface which allows to receive reply on request context data +// RequestCtx is helper interface which allows to receive reply on request. type RequestCtx interface { - // ReceiveReply receives a reply from VPP (blocks until a reply is delivered from VPP, or until an error occurs). - // The reply will be decoded into the msg argument. Error will be returned if the response cannot be received or decoded. + // ReceiveReply receives a reply from VPP (blocks until a reply is delivered + // from VPP, or until an error occurs). The reply will be decoded into the msg + // argument. Error will be returned if the response cannot be received or decoded. ReceiveReply(msg Message) error } -// MultiRequestCtx is helper interface which allows to receive reply on multi-request context data +// MultiRequestCtx is helper interface which allows to receive reply on multi-request. type MultiRequestCtx interface { - // ReceiveReply receives a reply from VPP (blocks until a reply is delivered from VPP, or until an error occurs). - // The reply will be decoded into the msg argument. If the last reply has been already consumed, lastReplyReceived is - // set to true. Do not use the message itself if lastReplyReceived is true - it won't be filled with actual data. - // Error will be returned if the response cannot be received or decoded. + // ReceiveReply receives a reply from VPP (blocks until a reply is delivered + // from VPP, or until an error occurs).The reply will be decoded into the msg + // argument. If the last reply has been already consumed, lastReplyReceived is + // set to true. Do not use the message itself if lastReplyReceived is + // true - it won't be filled with actual data.Error will be returned if the + // response cannot be received or decoded. ReceiveReply(msg Message) (lastReplyReceived bool, err error) } -// NotifSubscription represents a subscription for delivery of specific notification messages. -type NotifSubscription struct { - NotifChan chan Message // channel where notification messages will be delivered to - MsgFactory func() Message // function that returns a new instance of the specific message that is expected as a notification - // TODO: use Message directly here, not a factory, eliminating need to allocation -} - -var registeredMessages = make(map[string]Message) - -// RegisterMessage is called from generated code to register message. -func RegisterMessage(x Message, name string) { - if _, ok := registeredMessages[name]; ok { - panic(fmt.Errorf("govpp: duplicate message registered: %s (%s)", name, x.GetCrcString())) - } - registeredMessages[name] = x -} - -// GetAllMessages returns list of all registered messages. -func GetAllMessages() map[string]Message { - return registeredMessages +// SubscriptionCtx is helper interface which allows to control subscription for +// notification events. +type SubscriptionCtx interface { + // Unsubscribe unsubscribes from receiving the notifications tied to the + // subscription context. + Unsubscribe() error }