improved docking / undocking API, #1877