implement generic job_completed event

[nathanblair]

Hey fishers,

I was putting together a config.fish and wanted to include some functionality that could benefit from overriding the job-finished hook/event.

In the documentation on fishshell.com there is a sample function in the function section showing some function notify .... It defines a function function _notify_job$job --on-job-exit $job --inherit-variable job ... but I can't find any documentation regarding any job-exit hooks or events.

When I copied the function into my own config.fish file I did not notice any of the behaviors I might have expected to happen, notably an \a beep being sent when a job was completed. My process looked like this:

> sleep 15 &
> sleep 15 &
> sleep 15 &

...all executed consecutively (within 1 second). Of course, after 15 seconds, I started receiving notifications in my prompt that jobs were being finished (Job X, "sleep 15 &" has ended).

I'd like to tap into (override) the print statements that get issued when these jobs are finished to write something that fits my theme a little better. Am I missing documentation that explains how to do this? From what I've seen the only builtin events I can hook are pre-exec, post-exec, and the prompt.

Thanks for any input!

[krader1961]

There is no way to override the message displayed when a background job completes. It's currently hardcoded in the C++ code; specifically in src/proc.cpp. If you think you can make a convincing argument for why that should be configurable we might consider it. But "fits (your) theme a little better" does not strike me as a compelling argument.

See man function for a list of events that fish will send. Event names however are just arbitrary strings. You can send you own named event using the emit command.

Technically the --on-job-exit flag does register an interest in a specific event (see the symbol EVENT_JOB_ID in the source) but because of how that event works you can't register an interest in it using the function --on-event flag.

[nathanblair]

Yeah, I ran a check just now and realized jobs was actually builtin, not in the fish functions list. Which is fine, its understandable why its there. However, I wanted to point out (and forgot to when I wrote the report) that another reason I opened an issue was because in the fishshell.com Documentation there is a section on Event Handlers that explicitly states an event handler exists for "when a process or job exits".

Now, maybe the job exit event does actually exist - it would still be useful, I think, to be able to hook into that even if I couldn't override the stock job ending behavior. If it doesn't, I might suggest removing that line from the fishshell.com documentation so as not to confuse newcomers like myself trying to familiarize ourselves with fish's (already great) capabilities!

[krader1961]

... there is a section on Event Handlers that explicitly states an event handler exists for "when a process or job exits".

Technically that statement is correct but I agree it is misleading. Because the event does not have a name you have to use function --on-job-exit rather than function --on-event. So the documentation should definitely be clarified. Thanks for pointing that out. We depend heavily on new fish users to bring these things to our attention so thanks for going to the trouble of opening this issue.

It might be worth creating a generic event name for when jobs complete. That would allow you to create a function that has $argv set to the job number, process group id, and job string (what jobs would show). If we did that we should probably modify the code in src/proc.cpp to only write its default hardcoded message if no function is listening for the job completion event. This seems like a niche feature that very few people would use. So I'm not going to spend my weekend implementing it 😄 Nonetheless, the idea has enough value that I'll leave this open as an enhancement request. If someone like yourself, @nathanblair, created a change for us to review we'd be happy to do so; otherwise it could be several years before someone tackles this enhancement.

[nathanblair]

Right. It might be something I try to peek into at some point in the semi-near future but as you said it'll probably only ever be a handful that might exploit that new capability. It sounds to me like this issue/enhancement is similar to prepending the prompt mode which, coincidentally, I was also dealing with earlier today!

Thanks for your time and consideration; if you are okay with keeping this open for a possible enhancement in the future then I'll not close it either.

[krader1961]

Let's leave it open. I think there is merit in the idea just not enough to make it likely any of the handful of core contributors will implement this in the near future. Which means that if you want it implemented sooner rather than later you'll probably have to do the work yourself, @nathanblair. Note that this should be a straightforward change once you get acquainted with the code and assuming you have minimal C++ skills.

[soumya92]

I think this would help both #2727 and #1018. It seems to me that this is just a matter of someone actually implementing the feature, and the feature itself is not contentious. Is that a reasonable reading of the current status?

That is, would the fish-shell maintainers accept a pull request that changed the current behaviour of printing the hardcoded string to instead call a function (fish_job_end_summary or something), with a default implementation of that function producing the same output?

Edit: as written earlier in #4319 (comment), except that instead of enumerating listeners, we would just move the print statement into the default function, since I see this as similar to fish_greeting or fish_title: sensible default out of the box, with the option to override by redefining.

If so, I would be wiling to take a look; on the surface it doesn't seem too complicated.

[soumya92]

Also, what do people think about handling the "terminated by signal" message the same way: fish_job_terminate_summary or similar? Or another argument to the same fish_job_end_summary? Or is leaving that hardcoded message in fine?

[zanchey]

That is, would the fish-shell maintainers accept a pull request that changed the current behaviour of printing the hardcoded string to instead call a function (fish_job_end_summary or something), with a default implementation of that function producing the same output?

Yes, I think we'd take something along those lines. The current strings are translated, I think, but it should be possible to do that from the function.

[soumya92]

Great! I'll try to put something together for review.

The current strings are translated, I think, but it should be possible to do that from the function.

Yeah, I think I've seen _ calls in fish functions, so hopefully that works the way I expect.