MIMIC Go API Guide

  1. Table of Contents
  2. Requirements
  3. The MIMIC Go API is an optional Update Wizard package, and requires the use of a recent version of the Go language.

    MIMIC has been tested with Go version 1.5.4 and 1.21.10 on Linux and version 1.13.5 and 1.22.1 on Windows.

    • Go version earlier than 1.18:

      1. Make sure you have Go installed, eg.

        $go version
        go version go1.5.4 linux/amd64
        

      2. Set your GOPATH environment variable to the golang subdirectory under your MIMIC install area, eg. if MIMIC is installed under the default /usr/local/mimic, in a bash:

        $export GOPATH=/usr/local/mimic/golang
        

        or on Windows

        $export GOPATH=c:/apps/mimic1920B5/golang
        

      3. Install required packages:

        $go get github.com/pborman/getopt/v2
        

    • Go version after 1.18:

      1. Make sure you have Go installed, eg.

        $go version
        go version go1.21.10 (Red Hat 1.21.10-1.el9_4) linux/amd64
        

      2. Copy the MIMIC Go API to your Go environment (somewhere under $GOPATH/src/ ), eg.

        $cd $GOPATH/src
        $cp -r /usr/local/mimic/golang/src/* .
        

      3. Link in the new code into your Go:

        $go mod init testapp
        go: creating new go.mod: module testapp
        go: to add module requirements and sums:
        	go mod tidy
        
        $go mod tidy
        go: finding module for package github.com/pborman/getopt/v2
        go: found github.com/pborman/getopt/v2 in github.com/pborman/getopt/v2 v2.1.0
        
        $cd Mimic
        
        $go mod init Mimic
        go: creating new go.mod: module Mimic
        go: to add module requirements and sums:
        	go mod tidy
        
        $cd ..
        
        $go mod edit -replace Mimic=./Mimic
        
        $go mod tidy
        go: found Mimic in Mimic v0.0.0-00010101000000-000000000000
        
        $go run testapp.go
        2024/07/01 11:43:37 TestApp: starting...
        ...
        

  4. Class Reference
  5. The Go API is modelled after the Java API. All classes and methods have the same name as in Java, except that Go programming constructs are used. Click here for the generated Java reference documentation.

  6. Hello, World!
  7. If you need to get familiar with Go, check this tutorial. The simplest Hello, World! program for the Go MIMIC API is with this source code in a file hello.go in any folder, eg. golang/ under your MIMIC private folder (eg. copy/paste the following text into the file):

    package main
    
    import (
    	"Mimic"
    	"log"
    )
    
    // globals
    var host string
    var port int
    var client Mimic.Client
    
    func main() {
    	host = "localhost"
    	port = int(Mimic.MGMT_PORT)
    
    	log.Printf("Connect to MIMIC at %s:%d\n", host, port)
    
    	client = Mimic.NewClient()
    	session, err := client.OpenSession (host, port)
    	if err != nil {
    		log.Fatalf ("cannot OpenSession %s:%d - %s", host, port, err.Error())
    	}
    
    	err = session.Cfg_new ("")
    	if err != nil {
    		log.Fatalf (err.Error())
    	}
    
    	err = session.Cfg_load ("agent.cfg", "")
    	if err != nil {
    		log.Fatalf (err.Error())
    	}
    
    	agent := Mimic.NewAgent (session, 1)
    	err = agent.Start()
    	if err != nil {
    		log.Fatalf (err.Error())
    	}
    
    	err = session.Disconnect()
    	if err != nil {
    		log.Fatalf (err.Error())
    	}
    }
    

    Make sure that your GOPATH points to the golang/ folder of your MIMIC installation, since it contains the MIMIC API, eg. set the GOPATH environment variable in bash if your MIMIC install is at the default path /usr/local/mimic:

    bash-4.2$ export GOPATH=/usr/local/mimic/golang
    

    then build and run it with the Go compiler, eg.
    % go run hello.go
    2022/07/05 08:54:51 Connect to MIMIC at localhost:9797
    

    While you are doing this, notice how your MIMICview reacts to each command - it synchronizes with the simulator to keep up with the latest state. When the first agent turns green, it has synchronized to your state. You have seen that you can control MIMIC from any number of clients using the MIMIC API.

  8. Examples
    • The testapp.go program is an small test program to exercise the MIMIC API. Run it as follows:

      $go run testapp.go
      2019/12/06 15:46:49 TestApp: starting...
      2019/12/06 15:46:49 client dump
      2019/12/06 15:46:49 number of sessions 1
      2019/12/06 15:46:49 session dump
      2019/12/06 15:46:49 host 127.0.0.1
      2019/12/06 15:46:49 port 9797
      2019/12/06 15:46:49 sock 0xc000010010
      2019/12/06 15:46:49 INFO: correctly prevented session.Connect from leaking connections
      2019/12/06 15:46:49 TestApp: config file = agent.cfg
      2019/12/06 15:46:49 TestApp: max agents = 20000
      2019/12/06 15:46:49 TestApp: last agent = 13900
      2019/12/06 15:46:49 TestApp: version = 19.20
      2019/12/06 15:46:49 TestApp: num clients = 1
      ...
      

    • The mimicd-threads program is an small diagnostic program to display sorted MIMICD threads CPU usage via the MIMIC API. The source code is in golang/src/mimicd-threads.go under the MIMIC install area.