-// 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
+// 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, options ...StreamOption) (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
}
-// 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
+// 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
}
+// StreamOption allows customizing a Stream. Available options are:
+// - WithRequestSize
+// - WithReplySize
+// - WithReplyTimeout
+type StreamOption func(Stream)
+
// ChannelProvider provides the communication channel with govpp core.
type ChannelProvider interface {
// NewAPIChannel returns a new channel for communication with VPP via govpp core.
// 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.
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.
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)
}
-// SubscriptionCtx is helper interface which allows to control subscription for notification events.
+// 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 unsubscribes from receiving the notifications tied to the
+ // subscription context.
Unsubscribe() error
}
-
-// map of registered messages
-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
-}
-
-// GetRegisteredMessages returns list of all registered messages.
-func GetRegisteredMessages() map[string]Message {
- return registeredMessages
-}
Code Review / govpp.git / blobdiff