github.com/jingruilea/kubeedge@v1.2.0-beta.0.0.20200410162146-4bb8902b3879/docs/modules/beehive.md (about) 1 # Beehive 2 3 ## Beehive Overview 4 5 Beehive is a messaging framework based on go-channels for communication between modules of KubeEdge. A module registered with beehive can communicate with other beehive modules if the name with which other beehive module is registered or the name of the group of the module is known. 6 Beehive supports following module operations: 7 8 1. Add Module 9 2. Add Module to a group 10 3. CleanUp (remove a module from beehive core and all groups) 11 12 Beehive supports following message operations: 13 14 1. Send to a module/group 15 2. Receive by a module 16 3. Send Sync to a module/group 17 4. Send Response to a sync message 18 19 ## Message Format 20 21 Message has 3 parts 22 23 1. Header: 24 1. ID: message ID (string) 25 2. ParentID: if it is a response to a sync message then parentID exists (string) 26 3. TimeStamp: time when message was generated (int) 27 4. Sync: flag to indicate if message is of type sync (bool) 28 2. Route: 29 1. Source: origin of message (string) 30 2. Group: the group to which the message has to be broadcasted (string) 31 3. Operation: what’s the operation on the resource (string) 32 4. Resource: the resource to operate on (string) 33 3. Content: content of the message (interface{}) 34 35 ## Register Module 36 37 1. On starting edgecore, each module tries to register itself with the beehive core. 38 2. Beehive core maintains a map named modules which has module name as key and implementation of module interface as value. 39 3. When a module tries to register itself with beehive core, beehive core checks from already loaded modules.yaml config file to check if the module is enabled. If it is enabled, it is added in the modules map or else it is added in the disabled modules map. 40 41 ## Channel Context Structure Fields 42 43 ### (_Important for understanding beehive operations_) 44 45 1. **channels:** channels is a map of string(key) which is name of module and chan(value) of message which will used to send message to the respective module. 46 2. **chsLock:** lock for channels map 47 3. **typeChannels:** typeChannels is a map of string(key)which is group name and (map of string(key) to chan(value) of message ) (value) which is map of name of each module in the group to the channels of corresponding module. 48 4. **typeChsLock:** lock for typeChannels map 49 5. **anonChannels:** anonChannels is a map of string(parentid) to chan(value) of message which will be used for sending response for a sync message. 50 6. **anonChsLock:** lock for anonChannels map 51 52 ## Module Operations 53 54 ### Add Module 55 56 1. Add module operation first creates a new channel of message type. 57 2. Then the module name(key) and its channel(value) is added in the channels map of channel context structure. 58 3. Eg: add edged module 59 60 ``` 61 coreContext.Addmodule(“edged”) 62 ``` 63 ### Add Module to Group 64 65 1. addModuleGroup first gets the channel of a module from the channels map. 66 2. Then the module and its channel is added in the typeChannels map where key is the group and in the value is a map in which (key is module name and value is the channel). 67 3. Eg: add edged in edged group. Here 1st edged is module name and 2nd edged is the group name. 68 69 ``` 70 coreContext.AddModuleGroup(“edged”,”edged”) 71 ``` 72 ### CleanUp 73 74 1. CleanUp deletes the module from channels map and deletes the module from all groups(typeChannels map). 75 2. Then the channel associated with the module is closed. 76 3. Eg: CleanUp edged module 77 78 ``` 79 coreContext.CleanUp(“edged”) 80 ``` 81 ## Message Operations 82 83 ### Send to a Module 84 85 1. Send gets the channel of a module from channels map. 86 2. Then the message is put on the channel. 87 3. Eg: send message to edged. 88 89 ``` 90 coreContext.Send(“edged”,message) 91 ``` 92 93 ### Send to a Group 94 95 1. SendToGroup gets all modules(map) from the typeChannels map. 96 2. Then it iterates over the map and sends the message on the channels of all modules in the map. 97 3. Eg: message to be sent to all modules in edged group. 98 99 ``` 100 coreContext.SendToGroup(“edged”,message) message will be sent to all modules in edged group. 101 ``` 102 ### Receive by a Module 103 104 1. Receive gets the channel of a module from channels map. 105 2. Then it waits for a message to arrive on that channel and returns the message. Error is returned if there is any. 106 3. Eg: receive message for edged module 107 108 ```go 109 msg, err := coreContext.Receive("edged") 110 ``` 111 ### SendSync to a Module 112 113 1. SendSync takes 3 parameters, (module, message and timeout duration) 114 2. SendSync first gets the channel of the module from the channels map. 115 3. Then the message is put on the channel. 116 4. Then a new channel of message is created and is added in anonChannels map where key is the messageID. 117 5. Then it waits for the message(response) to be received on the anonChannel it created till timeout. 118 6. If message is received before timeout, message is returned with nil error or else timeout error is returned. 119 7. Eg: send sync to edged with timeout duration 60 seconds 120 121 ```go 122 response, err := coreContext.SendSync("edged",message,60*time.Second) 123 ``` 124 ### SendSync to a Group 125 126 1. Get the list of modules from typeChannels map for the group. 127 2. Create a channel of message with size equal to the number of modules in that group and put in anonChannels map as value with key as messageID. 128 3. Send the message on channels of all the modules. 129 4. Wait till timeout. If the length of anonChannel = no of modules in that group, check if all the messages in the channel have parentID = messageID. If no return error else return nil error. 130 5. If timeout is reached,return timeout error. 131 6. Eg: send sync message to edged group with timeout duration 60 seconds 132 133 ```go 134 err := coreContext.SendToGroupSync("edged",message,60*time.Second) 135 ``` 136 137 ### SendResp to a sync message 138 139 1. SendResp is used to send response for a sync message. 140 2. The messageID for which response is sent needs to be in the parentID of the response message. 141 3. When SendResp is called, it checks if for the parentID of response message , there exists a channel is anonChannels. 142 4. If channel exists, message(response) is sent on that channel. 143 5. Or else error is logged. 144 ```go 145 coreContext.SendResp(respMessage) 146 ```