rdb_ocean_create_pending Function

public function rdb_ocean_create_pending(nml_text, nml_len, handle_out) result(status) bind(c, name="rdb_ocean_create_pending")

P2.5 phase 1 of 2: build + validate a config and allocate a handle EXACTLY like rdb_ocean_create_from_string, but stop there — does NOT run engine_setup or map the device. Claims the single-live-handle guard immediately (a second concurrent create/create_pending is refused from this point on, even though engine_setup has not yet touched any process-global state — the invariant is “one handle mid-create at a time”, not merely “one finished one”).

Between this call and rdb_ocean_create_finalize, the rdb_ocean_stage_* entry points below inject geometry (bathymetry, grid metrics, topology) that engine_setup consumes — exactly the window passive-tracer registration already needed (registry_locked closes at enter_data, rdb_multilayer_state.F90). A caller with no geometry to inject has no reason to use this entry point — rdb_ocean_create_from_string remains the normal one-call path and is completely unaffected by this phase.

Arguments

Type IntentOptional Attributes Name
character(kind=c_char, len=1), intent(in) :: nml_text(nml_len)
integer(kind=c_int), intent(in), value :: nml_len
type(c_ptr), intent(out) :: handle_out

Return Value integer(kind=c_int)


Calls

proc~~rdb_ocean_create_pending~~CallsGraph proc~rdb_ocean_create_pending rdb_ocean_create_pending proc~build_pending_handle build_pending_handle proc~rdb_ocean_create_pending->proc~build_pending_handle proc~c_to_f_string c_to_f_string proc~rdb_ocean_create_pending->proc~c_to_f_string proc~error_ring_clear error_ring_clear proc~rdb_ocean_create_pending->proc~error_ring_clear proc~error_ring_push error_ring_push proc~rdb_ocean_create_pending->proc~error_ring_push proc~comm_env_init comm_env_init proc~build_pending_handle->proc~comm_env_init proc~handle_check handle_check proc~build_pending_handle->proc~handle_check proc~handle_create handle_create proc~build_pending_handle->proc~handle_create proc~handle_destroy handle_destroy proc~build_pending_handle->proc~handle_destroy proc~read_config_from_string read_config_from_string proc~build_pending_handle->proc~read_config_from_string proc~validate_config validate_config proc~build_pending_handle->proc~validate_config comm_world comm_world proc~comm_env_init->comm_world pic_mpi_init pic_mpi_init proc~comm_env_init->pic_mpi_init proc~read_config_from_string_impl read_config_from_string_impl proc~read_config_from_string->proc~read_config_from_string_impl proc~validate_config->proc~error_ring_push cav_dz cav_dz proc~validate_config->cav_dz error error proc~validate_config->error info info proc~validate_config->info proc~aniso_mode_is_implemented aniso_mode_is_implemented proc~validate_config->proc~aniso_mode_is_implemented proc~bbl_glue_is_effective bbl_glue_is_effective proc~validate_config->proc~bbl_glue_is_effective proc~bdrag_variant_is_implemented bdrag_variant_is_implemented proc~validate_config->proc~bdrag_variant_is_implemented proc~bkgnd_henyey_conflicts_profile bkgnd_henyey_conflicts_profile proc~validate_config->proc~bkgnd_henyey_conflicts_profile proc~cavity_draft_is_uniform cavity_draft_is_uniform proc~validate_config->proc~cavity_draft_is_uniform proc~check_dataovr_file check_dataovr_file proc~validate_config->proc~check_dataovr_file proc~dataovr_any_tag_set dataovr_any_tag_set proc~validate_config->proc~dataovr_any_tag_set proc~dataovr_entry_is_valid dataovr_entry_is_valid proc~validate_config->proc~dataovr_entry_is_valid proc~dataovr_freshwater_needs_components dataovr_freshwater_needs_components proc~validate_config->proc~dataovr_freshwater_needs_components proc~dataovr_time_is_valid dataovr_time_is_valid proc~validate_config->proc~dataovr_time_is_valid proc~diag_density_levels_ok diag_density_levels_ok proc~validate_config->proc~diag_density_levels_ok proc~fail fail proc~validate_config->proc~fail proc~forcing_components_need_thermo forcing_components_need_thermo proc~validate_config->proc~forcing_components_need_thermo proc~gprime_nz_is_supported gprime_nz_is_supported proc~validate_config->proc~gprime_nz_is_supported proc~has_biharmonic_backstop has_biharmonic_backstop proc~validate_config->proc~has_biharmonic_backstop proc~ice_hlim_count ice_hlim_count proc~validate_config->proc~ice_hlim_count proc~ice_hlim_spec_is_valid ice_hlim_spec_is_valid proc~validate_config->proc~ice_hlim_spec_is_valid proc~ice_ic_parse_conc_config ice_ic_parse_conc_config proc~validate_config->proc~ice_ic_parse_conc_config proc~ice_t_freeze ice_t_freeze proc~validate_config->proc~ice_t_freeze proc~kpp_sw_method_is_implemented kpp_sw_method_is_implemented proc~validate_config->proc~kpp_sw_method_is_implemented proc~lateral_closure_conflicts_smag_ah lateral_closure_conflicts_smag_ah proc~validate_config->proc~lateral_closure_conflicts_smag_ah proc~lateral_closure_is_implemented lateral_closure_is_implemented proc~validate_config->proc~lateral_closure_is_implemented proc~leith_biharm_is_inert leith_biharm_is_inert proc~validate_config->proc~leith_biharm_is_inert proc~nz_stack_is_sufficient nz_stack_is_sufficient proc~validate_config->proc~nz_stack_is_sufficient proc~nz_stack_required nz_stack_required proc~validate_config->proc~nz_stack_required proc~ocean_bc_type_from_string ocean_bc_type_from_string proc~validate_config->proc~ocean_bc_type_from_string proc~ocean_bt_rem_from_visc_rem_on ocean_bt_rem_from_visc_rem_on proc~validate_config->proc~ocean_bt_rem_from_visc_rem_on proc~ocean_bt_visc_rem_producer_on ocean_bt_visc_rem_producer_on proc~validate_config->proc~ocean_bt_visc_rem_producer_on proc~p_top_has_producer p_top_has_producer proc~validate_config->proc~p_top_has_producer proc~parse_bdrag_variant parse_bdrag_variant proc~validate_config->proc~parse_bdrag_variant proc~parse_cavity_draft_sign parse_cavity_draft_sign proc~validate_config->proc~parse_cavity_draft_sign proc~parse_cavity_exchange_law parse_cavity_exchange_law proc~validate_config->proc~parse_cavity_exchange_law proc~parse_cavity_freshwater parse_cavity_freshwater proc~validate_config->proc~parse_cavity_freshwater proc~parse_cavity_ice_mode parse_cavity_ice_mode proc~validate_config->proc~parse_cavity_ice_mode proc~parse_cavity_volume_comp parse_cavity_volume_comp proc~validate_config->proc~parse_cavity_volume_comp proc~parse_lateral_closure parse_lateral_closure proc~validate_config->proc~parse_lateral_closure proc~parse_opgf_variant parse_opgf_variant proc~validate_config->proc~parse_opgf_variant proc~parse_pv_adv_scheme parse_pv_adv_scheme proc~validate_config->proc~parse_pv_adv_scheme proc~parse_pv_variant parse_pv_variant proc~validate_config->proc~parse_pv_variant proc~parse_tdrag_variant parse_tdrag_variant proc~validate_config->proc~parse_tdrag_variant proc~parse_tfreeze_set parse_tfreeze_set proc~validate_config->proc~parse_tfreeze_set proc~parse_tracer_recon parse_tracer_recon proc~validate_config->proc~parse_tracer_recon proc~parse_vcoord_type parse_vcoord_type proc~validate_config->proc~parse_vcoord_type proc~parse_z_fixed_profile parse_z_fixed_profile proc~validate_config->proc~parse_z_fixed_profile proc~pseudo_salt_conflicts_ice pseudo_salt_conflicts_ice proc~validate_config->proc~pseudo_salt_conflicts_ice proc~pseudo_salt_conflicts_restore pseudo_salt_conflicts_restore proc~validate_config->proc~pseudo_salt_conflicts_restore proc~pseudo_salt_needs_thermo_warning pseudo_salt_needs_thermo_warning proc~validate_config->proc~pseudo_salt_needs_thermo_warning proc~pv_adv_required_nghost pv_adv_required_nghost proc~validate_config->proc~pv_adv_required_nghost proc~pv_adv_scheme_is_implemented pv_adv_scheme_is_implemented proc~validate_config->proc~pv_adv_scheme_is_implemented proc~pv_variant_is_implemented pv_variant_is_implemented proc~validate_config->proc~pv_variant_is_implemented proc~sponge_ramp_is_valid sponge_ramp_is_valid proc~validate_config->proc~sponge_ramp_is_valid proc~sponge_source_is_implemented sponge_source_is_implemented proc~validate_config->proc~sponge_source_is_implemented proc~sponge_target_is_implemented sponge_target_is_implemented proc~validate_config->proc~sponge_target_is_implemented proc~substep_drag_ignores_bdrag_form substep_drag_ignores_bdrag_form proc~validate_config->proc~substep_drag_ignores_bdrag_form proc~sw_source_is_implemented sw_source_is_implemented proc~validate_config->proc~sw_source_is_implemented proc~tdrag_variant_is_implemented tdrag_variant_is_implemented proc~validate_config->proc~tdrag_variant_is_implemented proc~tidal_mixing_is_inert tidal_mixing_is_inert proc~validate_config->proc~tidal_mixing_is_inert proc~tracer_recon_required_nghost tracer_recon_required_nghost proc~validate_config->proc~tracer_recon_required_nghost proc~vcoord_h_min_is_coherent vcoord_h_min_is_coherent proc~validate_config->proc~vcoord_h_min_is_coherent proc~warn_unknown_bc warn_unknown_bc proc~validate_config->proc~warn_unknown_bc proc~z_fixed_nominal_dz z_fixed_nominal_dz proc~validate_config->proc~z_fixed_nominal_dz proc~zfixed_cavity_nu_h_below_envelope zfixed_cavity_nu_h_below_envelope proc~validate_config->proc~zfixed_cavity_nu_h_below_envelope to_string to_string proc~validate_config->to_string warning warning proc~validate_config->warning zf_dz zf_dz proc~validate_config->zf_dz proc~check_dataovr_file->error proc~fail->proc~error_ring_push proc~fail->error proc~ice_hlim_spec_is_valid->proc~ice_hlim_count proc~ice_hlim_spec_is_valid->to_string proc~parse_kpp_sw_method parse_kpp_sw_method proc~kpp_sw_method_is_implemented->proc~parse_kpp_sw_method proc~nz_stack_is_sufficient->proc~nz_stack_required to_lower to_lower proc~ocean_bc_type_from_string->to_lower proc~ocean_bt_visc_rem_producer_on->proc~ocean_bt_rem_from_visc_rem_on proc~ocean_bt_forcing_visc_rem_on ocean_bt_forcing_visc_rem_on proc~ocean_bt_visc_rem_producer_on->proc~ocean_bt_forcing_visc_rem_on proc~ocean_bt_renorm_visc_rem_on ocean_bt_renorm_visc_rem_on proc~ocean_bt_visc_rem_producer_on->proc~ocean_bt_renorm_visc_rem_on proc~read_config_from_string_impl->proc~error_ring_push proc~read_config_from_string_impl->error parse_errors parse_errors proc~read_config_from_string_impl->parse_errors proc~apply_cartesian_degrees apply_cartesian_degrees proc~read_config_from_string_impl->proc~apply_cartesian_degrees proc~apply_time_unit_cascade apply_time_unit_cascade proc~read_config_from_string_impl->proc~apply_time_unit_cascade proc~build_rdb_schema build_rdb_schema proc~read_config_from_string_impl->proc~build_rdb_schema proc~schema_parse_lines nml_schema_t%schema_parse_lines proc~read_config_from_string_impl->proc~schema_parse_lines proc~split_to_lines split_to_lines proc~read_config_from_string_impl->proc~split_to_lines proc~vcoord_h_min_role vcoord_h_min_role proc~vcoord_h_min_is_coherent->proc~vcoord_h_min_role proc~warn_unknown_bc->warning proc~zfixed_cavity_nu_h_below_envelope->proc~parse_vcoord_type proc~apply_cartesian_degrees->error proc~apply_cartesian_degrees->info proc~apply_cartesian_degrees->to_string proc~apply_time_unit_cascade->error proc~register_boundary register_boundary proc~build_rdb_schema->proc~register_boundary proc~register_conv register_conv proc~build_rdb_schema->proc~register_conv proc~register_ddiff register_ddiff proc~build_rdb_schema->proc~register_ddiff proc~register_epbl register_epbl proc~build_rdb_schema->proc~register_epbl proc~register_foxkemper register_foxkemper proc~build_rdb_schema->proc~register_foxkemper proc~register_gm register_gm proc~build_rdb_schema->proc~register_gm proc~register_grid register_grid proc~build_rdb_schema->proc~register_grid proc~register_initial_condition register_initial_condition proc~build_rdb_schema->proc~register_initial_condition proc~register_kappa_shear register_kappa_shear proc~build_rdb_schema->proc~register_kappa_shear proc~register_logging register_logging proc~build_rdb_schema->proc~register_logging proc~register_meke register_meke proc~build_rdb_schema->proc~register_meke proc~register_mpi register_mpi proc~build_rdb_schema->proc~register_mpi proc~register_nonhydrostatic register_nonhydrostatic proc~build_rdb_schema->proc~register_nonhydrostatic proc~register_ocean_bc register_ocean_bc proc~build_rdb_schema->proc~register_ocean_bc proc~register_ocean_bdrag register_ocean_bdrag proc~build_rdb_schema->proc~register_ocean_bdrag proc~register_ocean_bt register_ocean_bt proc~build_rdb_schema->proc~register_ocean_bt proc~register_ocean_cavity_dyn register_ocean_cavity_dyn proc~build_rdb_schema->proc~register_ocean_cavity_dyn proc~register_ocean_cavity_melt register_ocean_cavity_melt proc~build_rdb_schema->proc~register_ocean_cavity_melt proc~register_ocean_continuity register_ocean_continuity proc~build_rdb_schema->proc~register_ocean_continuity proc~register_ocean_coriolis register_ocean_coriolis proc~build_rdb_schema->proc~register_ocean_coriolis proc~register_ocean_data register_ocean_data proc~build_rdb_schema->proc~register_ocean_data proc~register_ocean_dataovr register_ocean_dataovr proc~build_rdb_schema->proc~register_ocean_dataovr proc~register_ocean_debug register_ocean_debug proc~build_rdb_schema->proc~register_ocean_debug proc~register_ocean_diag register_ocean_diag proc~build_rdb_schema->proc~register_ocean_diag proc~register_ocean_eos register_ocean_eos proc~build_rdb_schema->proc~register_ocean_eos proc~register_ocean_forcing register_ocean_forcing proc~build_rdb_schema->proc~register_ocean_forcing proc~register_ocean_geothermal register_ocean_geothermal proc~build_rdb_schema->proc~register_ocean_geothermal proc~register_ocean_grid register_ocean_grid proc~build_rdb_schema->proc~register_ocean_grid proc~register_ocean_hdiff register_ocean_hdiff proc~build_rdb_schema->proc~register_ocean_hdiff proc~register_ocean_hvisc register_ocean_hvisc proc~build_rdb_schema->proc~register_ocean_hvisc proc~register_ocean_ic register_ocean_ic proc~build_rdb_schema->proc~register_ocean_ic proc~register_ocean_ice register_ocean_ice proc~build_rdb_schema->proc~register_ocean_ice proc~register_ocean_ice_ic register_ocean_ice_ic proc~build_rdb_schema->proc~register_ocean_ice_ic proc~register_ocean_isopycnal register_ocean_isopycnal proc~build_rdb_schema->proc~register_ocean_isopycnal proc~register_ocean_mpi register_ocean_mpi proc~build_rdb_schema->proc~register_ocean_mpi proc~register_ocean_pgf register_ocean_pgf proc~build_rdb_schema->proc~register_ocean_pgf proc~register_ocean_psurf register_ocean_psurf proc~build_rdb_schema->proc~register_ocean_psurf proc~register_ocean_restore register_ocean_restore proc~build_rdb_schema->proc~register_ocean_restore proc~register_ocean_sponge register_ocean_sponge proc~build_rdb_schema->proc~register_ocean_sponge proc~register_ocean_tdrag register_ocean_tdrag proc~build_rdb_schema->proc~register_ocean_tdrag proc~register_ocean_thermo register_ocean_thermo proc~build_rdb_schema->proc~register_ocean_thermo proc~register_ocean_tides register_ocean_tides proc~build_rdb_schema->proc~register_ocean_tides proc~register_ocean_topo register_ocean_topo proc~build_rdb_schema->proc~register_ocean_topo proc~register_ocean_tracers register_ocean_tracers proc~build_rdb_schema->proc~register_ocean_tracers proc~register_ocean_vdiff register_ocean_vdiff proc~build_rdb_schema->proc~register_ocean_vdiff proc~register_ocean_vmix register_ocean_vmix proc~build_rdb_schema->proc~register_ocean_vmix proc~register_ocean_wetdry register_ocean_wetdry proc~build_rdb_schema->proc~register_ocean_wetdry proc~register_ocean_zinit register_ocean_zinit proc~build_rdb_schema->proc~register_ocean_zinit proc~register_output register_output proc~build_rdb_schema->proc~register_output proc~register_physics register_physics proc~build_rdb_schema->proc~register_physics proc~register_porous register_porous proc~build_rdb_schema->proc~register_porous proc~register_redi register_redi proc~build_rdb_schema->proc~register_redi proc~register_sim register_sim proc~build_rdb_schema->proc~register_sim proc~register_slopes register_slopes proc~build_rdb_schema->proc~register_slopes proc~register_tidal_mixing register_tidal_mixing proc~build_rdb_schema->proc~register_tidal_mixing proc~register_time register_time proc~build_rdb_schema->proc~register_time proc~register_tracer register_tracer proc~build_rdb_schema->proc~register_tracer proc~register_varmix register_varmix proc~build_rdb_schema->proc~register_varmix proc~register_vcoord register_vcoord proc~build_rdb_schema->proc~register_vcoord proc~register_wavespeed register_wavespeed proc~build_rdb_schema->proc~register_wavespeed proc~parse_from_lines parse_from_lines proc~schema_parse_lines->proc~parse_from_lines proc~post_parse_validate post_parse_validate proc~schema_parse_lines->proc~post_parse_validate proc~reset_state reset_state proc~schema_parse_lines->proc~reset_state

Variables

Type Visibility Attributes Name Initial
type(c_ptr), private :: c_handle
type(ocean_handle_t), private, pointer :: h
character(len=:), private, allocatable :: text

Source Code

   function rdb_ocean_create_pending(nml_text, nml_len, handle_out) &
      result(status) bind(c, name="rdb_ocean_create_pending")
      !! P2.5 phase 1 of 2: build + validate a config and allocate a
      !! handle EXACTLY like `rdb_ocean_create_from_string`, but stop
      !! there — does NOT run `engine_setup` or map the device. Claims the
      !! single-live-handle guard immediately (a second concurrent
      !! create/create_pending is refused from this point on, even though
      !! `engine_setup` has not yet touched any process-global state — the
      !! invariant is "one handle mid-create at a time", not merely "one
      !! finished one").
      !!
      !! Between this call and `rdb_ocean_create_finalize`, the
      !! `rdb_ocean_stage_*` entry points below inject geometry
      !! (bathymetry, grid metrics, topology) that `engine_setup` consumes
      !! — exactly the window passive-tracer registration already needed
      !! (`registry_locked` closes at `enter_data`, `rdb_multilayer_state.F90`).
      !! A caller with no geometry to inject has no reason to use this
      !! entry point — `rdb_ocean_create_from_string` remains the
      !! normal one-call path and is completely unaffected by this phase.
      integer(c_int), intent(in), value :: nml_len
      character(kind=c_char), intent(in) :: nml_text(nml_len)
      type(c_ptr), intent(out) :: handle_out
      integer(c_int) :: status

      type(c_ptr) :: c_handle
      type(ocean_handle_t), pointer :: h
      character(len=:), allocatable :: text

      handle_out = c_null_ptr
      call error_ring_clear()

      if (g_handle_live) then
         call error_ring_push("rdb_ocean_create_pending: a live ocean handle "// &
                              "already exists in this process (multi-instance is not "// &
                              "supported) — destroy it before creating another")
         status = int(OCEAN_STATUS_ERR_ALREADY_EXISTS, c_int)
         return
      end if

      call c_to_f_string(nml_text, nml_len, text)

      call build_pending_handle(text, c_handle, h, status)
      if (status /= int(OCEAN_STATUS_OK, c_int)) return   ! already destroyed

      h%is_pending = .true.
      g_handle_live = .true.
      handle_out = c_handle
   end function rdb_ocean_create_pending