Session boundaries


Session boundaries

One of the main purposes of an environment is to indicate when your program will start to use Gurobi, and when it is done. When Gurobi is running on your own machine, creating an environment will obtain a license, and disposing of the environment will release that license. When you are a client of a Gurobi Compute Server, starting an environment will start a job on the server (or enter the queue if the server is fully occupied). Disposing of the environment will end that job, allowing the next job in the queue to start. On Gurobi Instant Cloud, creating an environment will launch a cloud instance (if it hasn't been launched already). Disposing of the environment will end that session, which may result in the cloud instance being shut down (depending on the policy you've set in your Instant Cloud configuration).

If your program repeatedly creates, solves, and destroys optimization models, we strongly recommend that you do so within a single Gurobi environment. Creating a Gurobi environment incurs overhead, ranging anywhere from a quick local license check all the way to spinning up a machine on the cloud. By reusing a single environment, you avoid paying this overhead multiple times.

We also recommend that you dispose of your environment as soon as your program is done using Gurobi. Doing so releases all resources associated with that session, which in many cases can make those resources available to other users. You should pay particular attention to this topic when using programming languages that perform garbage-collection. While it is true that environments will be disposed of eventually by automated garbage-collection, that will often happen much earlier if you dispose of them explicitly.

The actual steps for disposing of an environment will depend on the API you are using:

Python
Call Model.dispose() on all Model objects, Env.dispose() on any Env objects you created, or disposeDefaultEnv() if you used the default environment instead. For example:
# Clean up model and environment
model.dispose()
env.dispose()
gp.disposeDefaultEnv()
Java
Call GRBModel.dispose() on all GRBModel objects, then call GRBEnv.dispose() on the GRBEnv object. For example:
  // Clean up model and environment
  model.dispose()
  env.dispose()
.NET
Call GRBModel.Dispose() on all GRBModel objects, then call GRBEnv.Dispose() on the GRBEnv object.
C++
Call the delete operator on all GRBModel objects, and then on the GRBEnv object.
C
Call GRBfreemodel() for each model, then call GRBfreeenv() for the Gurobi environment. For example:
  /* Clean up model and environment */
  GRBfreemodel(model);
  GRBfreeenv(env);

Note that the boundaries established by an environment are for a single thread. Gurobi environments are not thread-safe, so you can't have more than one thread of control within a single environment. You can however have a single program that launches multiple threads, each with its own environment.

In Python you can take advantage of context managers for environment and model objects. Using them will guarantee that these objects are automatically disposed of. Refer to Env class documentation for more information. A typical use pattern is also shown in the example mip1_remote.py.