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  ```