org.gnome.glib.SpawnChildSetupFunc Maven / Gradle / Ivy

Go to download
// Java-GI - Java language bindings for GObject-Introspection-based libraries
// Copyright (C) 2022-2024 Jan-Willem Harmannij
//
// SPDX-License-Identifier: LGPL-2.1-or-later
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, see .
//
// This file has been generated with Java-GI.
// Do not edit this file directly!
// Visit  for more information.
//
package org.gnome.glib;

import io.github.jwharm.javagi.interop.Interop;
import java.lang.FunctionalInterface;
import java.lang.foreign.Arena;
import java.lang.foreign.FunctionDescriptor;
import java.lang.foreign.Linker;
import java.lang.foreign.MemorySegment;
import java.lang.foreign.ValueLayout;
import java.lang.invoke.MethodHandle;
import java.lang.invoke.MethodHandles;
import javax.annotation.processing.Generated;
import org.jetbrains.annotations.Nullable;

/**
 * Functional interface declaration of the {@code SpawnChildSetupFunc} callback.
 */
@FunctionalInterface
@Generated("io.github.jwharm.JavaGI")
public interface SpawnChildSetupFunc {
    /**
     * Specifies the type of the setup function passed to g_spawn_async(),
     * g_spawn_sync() and g_spawn_async_with_pipes(), which can, in very
     * limited ways, be used to affect the child's execution.
     * 
     * On POSIX platforms, the function is called in the child after GLib
     * has performed all the setup it plans to perform, but before calling
     * exec(). Actions taken in this function will only affect the child,
     * not the parent.
     * 

     * On Windows, the function is called in the parent. Its usefulness on
     * Windows is thus questionable. In many cases executing the child setup
     * function in the parent can have ill effects, and you should be very
     * careful when porting software to Windows that uses child setup
     * functions.
     * 

     * However, even on POSIX, you are extremely limited in what you can
     * safely do from a {@code GSpawnChildSetupFunc}, because any mutexes that were
     * held by other threads in the parent process at the time of the fork()
     * will still be locked in the child process, and they will never be
     * unlocked (since the threads that held them don't exist in the child).
     * POSIX allows only async-signal-safe functions (see signal(7)) to be
     * called in the child between fork() and exec(), which drastically limits
     * the usefulness of child setup functions.
     * 
     * In particular, it is not safe to call any function which may
     * call malloc(), which includes POSIX functions such as setenv().
     * If you need to set up the child environment differently from
     * the parent, you should use g_get_environ(), g_environ_setenv(),
     * and g_environ_unsetenv(), and then pass the complete environment
     * list to the {@code g_spawn...} function.
     */
    void run(@Nullable MemorySegment data);

    /**
     * The {@code upcall} method is called from native code. The parameters
     * are marshaled and {@link #run} is executed.
     */
    default void upcall(MemorySegment data) {
        Arena _arena = Arena.ofAuto();
        run(data);
    }

    /**
     * Creates a native function pointer to the {@link #upcall} method.
     *
     * @return the native function pointer
     */
    default MemorySegment toCallback(Arena arena) {
        FunctionDescriptor _fdesc = FunctionDescriptor.ofVoid(ValueLayout.ADDRESS);
        MethodHandle _handle = Interop.upcallHandle(MethodHandles.lookup(), SpawnChildSetupFunc.class, _fdesc);
        return Linker.nativeLinker().upcallStub(_handle.bindTo(this), _fdesc, arena);
    }
}