[PATCH 2/2] compositor: Document routines relating to idle behavior

[Bryce Harrington]

On Tue, Dec 22, 2015 at 04:24:18PM +0200, Pekka Paalanen wrote:
> Hi Bryce
> 
> On Fri, 11 Dec 2015 13:11:38 -0800
> Bryce Harrington <bryce at osg.samsung.com> wrote:
> 
> > Signed-off-by: Bryce Harrington <bryce at osg.samsung.com>
> > ---
> >  src/compositor.c | 46 ++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 46 insertions(+)
> > 
> > diff --git a/src/compositor.c b/src/compositor.c
> > index 254e9e4..3e1f588 100644
> > --- a/src/compositor.c
> > +++ b/src/compositor.c
> > @@ -3817,6 +3817,11 @@ bind_subcompositor(struct wl_client *client,
> >  				       compositor, NULL);
> >  }
> >  
> > +/** Set a DPMS mode on all of the compositor's outputs
> > + *
> > + * \param compositor The compositor instance
> > + * \param state The DPMS state the outputs will be set to
> > + */
> 
> Ok.
> 
> >  static void
> >  weston_compositor_dpms(struct weston_compositor *compositor,
> >  		       enum dpms_enum state)
> > @@ -3828,6 +3833,17 @@ weston_compositor_dpms(struct weston_compositor *compositor,
> >  			output->set_dpms(output, state);
> >  }
> >  
> > +/** Restores the compositor to active status
> > + *
> > + * \param compositor The compositor instance
> > + *
> > + * If the compositor was in a sleeping mode, all outputs are powered
> > + * back on via DPMS.  Otherwise if the compositor was inactive
> > + * (idle/locked, offscreen, or sleeping) then the compositor's wake
> > + * signal will fire.
> > + *
> > + * Resets the idle timer by one second.
> 
> Should be: Restarts the idle timer.
> 
> > + */
> >  WL_EXPORT void
> >  weston_compositor_wake(struct weston_compositor *compositor)
> >  {
> > @@ -3852,6 +3868,17 @@ weston_compositor_wake(struct weston_compositor *compositor)
> >  	}
> >  }
> >  
> > +/** Turns off rendering and frame events for the compositor.
> > + *
> > + * \param compositor The compositor instance
> > + *
> > + * This is used for example to prevent further rendering while the
> > + * compositor is shutting down.
> > + *
> 
> Add: Stops the idle timer.
> 
> Checking the call sites of this function, this seems to be mostly used
> when VT-switching away. The shutdown-path is good to mention because
> it's not calling this function but still uses offscreen mode.
> 
> > + * \note When offscreen state is entered, outputs will be powered
> > + * back on if they were sleeping (in DPMS off mode), even though
> > + * no rendering will be performed.
> > + */
> >  WL_EXPORT void
> >  weston_compositor_offscreen(struct weston_compositor *compositor)
> >  {
> > @@ -3867,6 +3894,14 @@ weston_compositor_offscreen(struct weston_compositor *compositor)
> >  	}
> >  }
> >  
> > +/** Powers down all attached output devices
> > + *
> > + * \param compositor The compositor instance
> > + *
> 
> Add: Stops the idle timer.
> 
> > + * Causes rendering to the outputs to cease, and no frame events to be
> > + * sent.  Only powers down the outputs if the compositor is not already
> > + * in sleep mode.
> > + */
> >  WL_EXPORT void
> >  weston_compositor_sleep(struct weston_compositor *compositor)
> >  {
> > @@ -3878,6 +3913,17 @@ weston_compositor_sleep(struct weston_compositor *compositor)
> >  	weston_compositor_dpms(compositor, WESTON_DPMS_OFF);
> >  }
> >  
> > +/** Sets compositor to idle mode
> > + *
> > + * \param data The compositor instance
> > + *
> 
> Add: This is called by the idle timer firing.
> 
> > + * Once the compositor is in idle mode it requires a wake action
> > + * (e.g. via weston_compositor_wake()) to restore it.  The compositor's
> > + * idle_signal will be triggered when the idle event occurs.
> > + *
> > + * Idleness can be inhibited by setting the compositor's idle_inhibit
> > + * property.
> > + */
> >  static int
> >  idle_handler(void *data)
> >  {
> 
> Looks good, no factual errors except that "one second". The other
> comments are just adding detail.
> 
> With these or equivalent changes:
> Reviewed-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>

Pushed with the recommended changes.

To ssh://git.freedesktop.org/git/wayland/weston
   c2be857..c9626a3  master -> master


> Thanks,
> pq

> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2
> 
> iQIVAwUBVnldEiNf5bQRqqqnAQg9Iw//V8et1ojljHk3RBVsZ7yJvykEbTHaR3O5
> dDITz+RZrIX6KAgsx8YXfPKeYFQKrhPRZauBOdq75E45PAqF85hdscGtdWLsU6MW
> SwRgiVBcTijTqLCY4aY30TWH7JfUxVm8emeDZOTBjeZENOavcyEGzwLjL46YzY70
> pCNCyNhykjZ59iVirIbFM6wuL7KEFXwILtcSZsH4Z+1+2SxT1W5WpE/6Fqlv3M/V
> wMZVaZphoQSo0nC/avZ3wURPIpcwVR18bTHgkJq3ouDhQzIzCdjSKJ2eB8bpmFk+
> OPJhjTuLsZF2xTW77uBB3E8pyqX3NtQGeYNqQ0M9oFgdamTuiejP6YjbZz0ueZj/
> hCkJx8srhb+x9Qig4N5J6A/SYmf3o3G9WWXlnoGlPKc4KuyNUTOisaoh6fQzpCeG
> X2b19LgWjGZ5ZKqeMiEELNMdGjtVnDXk1lU21cUXhE8+niBWOHeNycV9lz/ibIrO
> 5VOrb/i54x14dUhJT3dPVJMuL6pDr3K/yt47Yy1mZlq85fUF8Hlr25csQBSCth7u
> quNgapGdnRJnbyD10OCZ5KNCn/1saEAlhZVbs2i0XhxuLJaXiD9NUe386rDDQKVv
> ILW5LuXz97xBWy6/fj9ZOXLdT7GfSleN8GNsGa43TW2TcD6V91xV1UFotLe+hIzi
> xBhF54neecs=
> =tBUB
> -----END PGP SIGNATURE-----